API v1.1.0 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
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. 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
Parameter | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Consists of |
Request body
Request body is a JSON object of the following structure:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID (GUID, 36 characters).
If a response for the request is not received from Koshelek for any reason, it is permitted to re-send the request using the same value of |
| String | Yes | Session ID obtained from scanned TOTP barcode or from QR code (32 characters; Latin letters and digits only; 6 characters for one-dimensional barcodes). |
| String | Yes | Merchant's store ID (GUID, 36 characters). |
| Yes | Cash desk (terminal) ID (up to 256 characters). | |
| Object CheckoutInvoice | Yes | Invoice data (refer to the CheckoutInvoice object). |
| Object User | Yes | Customer data. |
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:
Field | Type | Mandatory | Description |
---|---|---|---|
| Boolean | Yes | Flag for automatic selection of Koshelek Pay as the default payment option at the checkout. If |
| Array of PaymentTypeAvailabilityInfo | Yes | Array containing a list of available payment methods. |
HTTP Status Code: 201
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:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | An ID you'll use in |
| Integer | Yes | Your waiting timeout before you should call |
HTTP Status Code: 422
An error occurred. Response body is a JSON object containing the error description.
Get available payment methods
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:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | ID received in request. |
| Boolean | Yes | Indicates completeness of request processing:
|
| Long | Yes | Instruction from server: make re-request after specified time (in milliseconds). Returned if |
| Boolean | Yes | Flag for automatic selection of Koshelek Pay as the default payment option at the checkout. If |
| Array of PaymentTypeAvailabilityInfo | Yes | List of available payment methods. |
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
Parameter | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Consists of |
Request body
Request body is a JSON object of the following structure:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID (GUID, 36 characters.) If a response for the request is not received from Koshelek for any reason, it is permitted to re-send the request using the same value of |
| String | Yes | Session ID obtained from scanned TOTP barcode or from QR code (up to 32 characters, Latin letters and digits only — or, 6 characters for one-dimensional barcodes). |
| String | Yes | Merchant's store ID (GUID, 36 characters). |
| String | Yes | Cash desk (terminal) ID (up to 256 characters). |
| Object CheckoutInvoice | Yes | Invoice data. |
| Object User | Yes | Customer data. |
| Array of PaymentMethod | Yes | Objects array defining available payment methods. |
Request example:
Response parameters
HTTP Status Code: 200
The response is processed.
Response body is a JSON object of the following structure:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID. |
| String | Yes | Transaction ID. |
| Enum | Yes | Transaction status:
|
| Object Slip | Depends on | Contains details of the completed transaction. Returned either for completed payment via bank (statuses: |
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.
All subsequent calls can be made with a delay of at least 250 ms between them.
Your cash desk software must expect receiving response within 30 seconds and initiate payment cancelation if this threshold is exceeded.
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:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID (GUID, 36 characters).
If a response for the request is not received from Koshelek for any reason, it is permitted to re-send the request using the same value of |
| String | No | ID for payment transaction (GUID, 36 characters). Omitted if |
| String | No | ID for payment cancel transaction (GUID, 36 characters). Omitted if |
Response parameters
HTTP Status Code: 200
The request is processed.
Response body is a JSON object of the following structure:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID. |
| String | Yes | ID for payment transaction. |
| String | No | ID for payment cancel transaction. |
| Enum | Yes | Transaction status:
|
| Enum | Yes | |
| Enum | Yes | Payment provider:
|
| Object Slip | Depends on the | Contains details of completed transaction. Returned either for completed payment via bank ( |
| Enum | No | Status of payment cancel transaction:
|
| Enum | No | Code of error occurred during payment or refund transaction. Returned only if |
Possible errorCode
values
errorCode
values1. For payment transaction:
Value | Description |
---|---|
| Transaction limit is exceeded. |
| Transaction amount is below the limit (equals 4 rubles). |
| General error code of payment provider. |
| No subscribed account found (applicable to |
| Payment declined by bank (applicable to |
2. For refund transaction:
Value | Description |
---|---|
| Refund rejected as transaction with this |
| Refund rejected due to one of the following reasons:
|
| Refund rejected as there is an ongoing refund already. Wait until the previous refund transaction with this |
| Refund rejected as the requested refund amount exceeds the one declared in payment transaction with this |
| General error code of payment provider. |
| Refund rejected due to payment transaction with this |
| No bank transfer order found in merchant's bank upon refund (applicable to |
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:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID (GUID, 36 characters).
If a response for the request is not received from Koshelek for any reason, it is permitted to re-send the request using the same value of |
| String | Yes | Payment transaction ID (GUID, 36 characters). |
| String | Yes | Merchant's store ID (GUID, 36 characters). |
| String | Yes | Cash desk (terminal) ID (up to 256 characters). |
| Object Invoice | Yes | Invoice data. |
| Object | No | Object for extra fields (e.g. discounts, bonuses etc.) in the "key-value" format. |
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:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID (GUID, 36 characters).
If a response for the request is not received from Koshelek for any reason, it is permitted to re-send the request using the same value of |
| String | Yes | Merchant's store ID (GUID, 36 characters). |
| String | Yes | Cash desk (terminal) ID (up to 256 characters). |
| String | Yes | Payment transaction ID subject for cancellation. |
Response parameters
HTTP Status Code: 200
The request is processed.
Response body is a JSON object of the following structure:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID. |
| String | Yes | Cancel transaction ID. |
| Enum | Yes | Cancellation transaction status:
|
| String | Yes | Payment transaction ID. |
| Enum | Yes | Payment transaction status after cancellation request processing:
|
| Object Slip | Depends on | Contains details of the completed transaction. Returned either for completed payment via bank ( |
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
Parameter | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Consists of a TOTP password and |
Request body
Request body is a JSON object of the following structure:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID (GUID, 36 characters).
If a response for the request is not received from Koshelek for any reason, it is permitted to re-send the request using the same value of |
| String | Yes | Merchant's store ID (GUID, 36 characters). |
| String | Yes | Cash desk (terminal) ID (up to 256 characters). |
| String | Yes | ID of payment transaction subject for refund (GUID, 36 characters). |
| Number | Yes | Refund amount in kopecks. Must not exceed payment amount. Only positive number. |
| Array of Item | Yes | Objects array defining commodity Items being returned. |
Response parameters
HTTP Status Code: 200
The request is processed.
Response body is a JSON object of the following structure:
Field | Type | Mandatory | Description |
---|---|---|---|
| String | Yes | Unique request ID. |
| String | Yes | Refund transaction ID. |
| Enum | Yes | Refund transaction status:
|
| String | Yes | Payment transaction ID. |
| Enum | Yes | Payment transaction ID status after refund request processing:
|
| Object Slip | No | Contains details of completed transaction. Returned either for completed payment via bank ( |
| Enum | No | Code of an error occurred during refund transaction. Returned only if |
Available errorCode
values
errorCode
valuesValue | Description |
---|---|
| Refund rejected as the transaction with this |
| Refund rejected due to one of the following reasons:
|
| Refund rejected as there is an ongoing refund already. Wait until the previous refund transaction with this |
| Refund rejected as the requested refund amount exceeds one declared in payment transaction with this |
| General error code of payment provider. |
| Refund rejected due to payment transaction with this |
| No bank transfer order found in merchant's bank upon refund (applicable to |
HTTP Status Code: 422
An error occurred.
Response body is a JSON object containing the error description.
Last updated