API v1.2.1 Requests
Koshelek Pay API
Documentation has moved
The information on this page is no longer updated and may be obsolete. The most current Koshelek documentation is now available at the new address:
In future versions of the document, new optional fields may be added to requests and / or responses.
On the merchant side, in order to ensure backward compatibility, it is necessary to ignore new optional fields when forming a request and when receiving responses from the server until changes to the software running on the merchant side are made.
Request list of available payment methods
Since Pay API v1.2.0 and onwards, the asynchronous processing of Request list of available payment methods and associated Get available payment methods request are no longer supported for new integrations.
The combination of these two methods implement obtaining the list of available payment methods in asynchronous manner, which is now deprecated. Instead, do use synchronous flow (with HTTP status code 200
).
HTTP method: POST
URL: /api/v1/merchant/availability-info/task
Description
Send purchase details to the Koshelek Pay server to create a task of populating a list of available payment methods.
Depending on the returned HTTP Status Code value, one of the following data receiving modes is used:
1) Synchronous. The response has the HTTP Status Code = 200, and the body contains the requested list.
2) Asynchronous (deprecated). The response has the HTTP Status Code = 201, and the body contains the availabilityInfoId
parameter and the headers contain Location header with URL, which must be periodically polled to receive a list of available payment methods using the /merchant/availability-info/{availabilityInfoId}
request.
Usage principles:
Request parameters
Request header
Request body
Request body is a JSON object of the following structure:
Response parameters
HTTP Status Code: 200
The request is processed. The response contains a list of available payment methods (synchronous mode).
Response body is a JSON object of the following structure:
HTTP Status Code: 201 (deprecated)
The request is processed. The response contains parameters you should use to obtain a list of available payment methods (asynchronous mode).
Response header:
Response body is a JSON object of the following structure:
HTTP Status Code: 422
An error occurred. Response body is a JSON object containing the error description.
Get available payment methods (deprecated)
Since Pay API v1.2.0 and onwards, the asynchronous processing of Request list of available payment methods and associated Get available payment methods request are no longer supported for new integrations.
The combination of these two methods implement obtaining the list of available payment methods in asynchronous manner, which is now deprecated. Instead, do use synchronous flow (with HTTP Status Code 200
).
HTTP method: GET
URL: /api/v1/merchant/availability-info/{availabilityInfoId}
Description
Used only in asynchronous mode, i.e. if /merchant/availability-info/task
call returns HTTP Status Code = 201.
To implement the polling principle, the request /merchant/availability-info/task
is to be followed by /merchant/availability-info/{availabilityInfoId}
.
Follow this sequence:
1. Call /merchant/availability-info/task
to obtain parameters availabilityInfoId
(your ID for subsequent polling request), and timeout
(the timeout after which you can start polling).
2. Once timeout
is over, call /merchant/availability-info/{availabilityInfoId}
, and repeat it with pollingTimeout
interval until you get computationComplete
= true
.
Request parameters
None.
Response parameters
HTTP Status Code: 200
The request is processed.
Response body is a JSON object of the following structure:
HTTP Status Code: 422
An error occurred.
Response body is a JSON object containing the error description.
Checkout
HTTP method: POST
URL: /api/v1/merchant/checkout
Description
At the checkout, provide Koshelek Pay with payment invoice information along with cardSession
of paying customer.
Request parameters
Request header
Request body
Request body is a JSON object of the following structure:
Request example:
Response parameters
HTTP Status Code: 200
The response is processed.
Response body is a JSON object of the following structure:
HTTP Status Code: 422
An error occurred.
Response body is a JSON object containing the error description.
Request status
HTTP method: POST
URL: /api/v1/merchant/transaction/status
Description
Request transaction status for payment / cancel payment operations. a. Implementation using postback/callback: Implement a POST request which the Koshelek server can call to inform you of operation result. This option is preferred, as you will receive the response right after a task is completed, without having to send repetitive poll requests as described in option b. Postback message body is the same as the response message in option b. We advise you to follow option b only in case of technical unavailability to establish direct communication between the Koshelek server and your server or cash desk software. POST response parameters: refer to Response parameters in option b. b. Implementation using polling
Timing rules
The following timing rules apply to this request:
Initial call: make one after 250 ms at the soonest but no later than 500 ms (merchant's configurable parameters).
All subsequent calls can be made with a delay of at least 250 ms between them (merchant's configurable parameters).
Your cash desk software must expect receiving response within 30 seconds and initiate payment cancelation if this threshold is exceeded (merchant's configurable parameres).
The implementation is up to you, but it is crucial to make sure there are no flows remained that keep polling our servers.
Request parameters
Request body
Request body is a JSON object of the following structure:
Response parameters
HTTP Status Code: 200
The request is processed.
Response body is a JSON object of the following structure:
HTTP Status Code: 422
An error occurred.
Response body is a JSON object containing the error description.
Send payment receipt
HTTP method: POST
URL: /api/v1/merchant/transaction/receipt
Description
Use this method to send a fiscal receipt of a completed transaction. The receipt information will be displayed in customer's Koshelek app.
Request parameters
Request body
Request body is a JSON object of the following structure:
Response parameters
HTTP Status Code: 200
The request is processed.
Response body is empty.
HTTP Status Code: 422
An error occurred.
Response body is a JSON object containing the error description.
Cancel payment
HTTP method: POST
URL: /api/v1/merchant/transaction/cancel
Description
Use this request to cancel payment transaction.
Request does not contain cancellation amount, as transaction cancellation is performed for full amount.
Request parameters
Request body
Request body is a JSON object of the following structure:
Response parameters
HTTP Status Code: 200
The request is processed.
Response body is a JSON object of the following structure:
HTTP Status Code: 422
An error occurred.
Response body is a JSON object containing the error description.
Refund payment
HTTP method: POST
URL: /api/v1/merchant/transaction/refund
Description
Use this request to initiate a refund of a completed payment transaction.
Request parameters
Request header
Request body
Request body is a JSON object of the following structure:
Response parameters
HTTP Status Code: 200
The request is processed.
Response body is a JSON object of the following structure:
HTTP Status Code: 422
An error occurred.
Response body is a JSON object containing the error description.
Last updated