API Connection
Connection requirements
Koshelek Pay API is provided by a dedicated Koshelek host.
API users are merchant's cash desk software and datacenter hosts.
API credentials, onboarding parameters and identifiers
To integrate with Koshelek Pay API, use the following parameters:
| Parameter | Description |
|---|---|
| host:port | Pay API host address. |
| login:password | Credentials for API request HTTP Basic Authentication. |
| Test URL | https://api-test.koshelek.app/ |
| Production URL | https://api.koshelek.app/ |
Next table defines merchant identifiers involved in data exchange via Pay API. Parameters specified in color are applicable to payment via Faster Payments System (SBP).
| Parameter | Context | Description |
|---|---|---|
brandName |
General | Merchant brand name. |
legalName |
General | Merchant legal name. |
Stores: storeId |
General | Full list of merchant's stores (service points) including their addresses. For each store, the storeId ID is given by Koshelek. This ID must be sent in each API request. |
postbackUrl |
General if cash desk has online host | URL used by the cash desk for accepting transaction status updates from the Koshelek Pay server. |
partnerLogin |
General if cash desk has online host | Login to authenticate at postbackUrl (HTTP Basic Authentication.) |
partnerPassword |
General if cash desk has online host | Password to authenticate at postbackUrl (HTTP Basic Authentication.) |
Terminals: terminalId |
General | List of merchant's payment terminal IDs. Every terminalId is assigned by the merchant per every terminal. This value is sent in each API request (the full list of IDs is not required before integration). Terminal IDs in the terminalId parameter must be unique within one storeId (store or service point). |
legalId |
FPS | Merchant legal name ID for FPS. Issued by the recipient bank at merchant's onboarding to FPS. The merchant must present this parameter to Koshelek team prior to API integration. |
merchantId |
FPS | Merchant identifier for FPS. Merchant receives this ID from merchant's acquiring bank involved in FPS transactions (Recipient bank). Mind strict one-to-one mapping between storeId and merchantId. The merchant must present this parameter to the Koshelek team prior to API integration. |
account |
FPS | Merchant's legal name account number for the recipient bank. The merchant must present this parameter to the Koshelek team prior to API integration. |
memberId |
FPS | Merchant's partner bank identifier for FPS. The merchant must present this parameter to the Koshelek team prior to API integration. |
paymentPurpose |
FPS | "Payment purpose" value applicable to transactions made from the linked account. The value can be agreed between the merchant and Koshelek only once, or can be passed in every POST /checkout request. |
subscriptionPurpose |
FPS | "Account subscription purpose" value agreed between the merchant and Koshelek during API integration. |
API request authorization
API communication relies on HTTPS with HTTP Basic Authentication (RFC 7617) for request authorization. Request authorization credentials are passed in HTTP header Authorization.
Info
Minimum requirement for TLS version: 1.2.
Message encoding
Both request and response messages use UTF-8 encoding.
Message format and structure
API requests expect content type in header: Content-Type ="application/json" and return response body in "application/json".
HTTP response codes
Successful API response will return data as described in API specification, along with HTTP response code: 200.
| Code | Description |
|---|---|
| 200 | Indicates successful processing of API request. |
| 422 | Indicates API request processing error. The response will contain JSON object with error description. In particular, this object contains a string message describing reason for occurred error in Russian. |
Error description object structure:
| Field | Type | Mandatory | Description |
|---|---|---|---|
code |
String | Yes | Error code (see below). |
details |
String | No | Error description. |
Error codes
| Code | Description |
|---|---|
UNKNOWN_SESSION_ID |
cardSession not found or invalid. |
UNKNOWN_TRANSACTION_ID |
transactionId not found. |
UNKNOWN_PARTNER_ID |
merchant not found. |
WRONG_TRANSACTION_STATE_CHANGE |
Requested transaction status transit is not possible. |
PAYMENT_TRANSACTION_IS_NOT_PAID |
There is no fulfilled payment for this payment transaction. |
CANCEL_REFUNDING_BY_BANK |
Refund was canceled by bank. |
TRANSACTION_FOR_SESSION_ID_ALREADY_EXISTS |
Transaction for this session already exists. |
TRANSACTION_FOR_SESSION_ID_ALREADY_PAYED |
Transaction already processed. |
TRANSACTION_IN_PROCESSING |
Transaction in progress. |