Connection to API

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:

https://developers.koshelek.app/en/

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
Login	Login for API request authentication (HTTP Basic Authentication is used)
Password	Password for API request authentication
API Base URL (test)	https://api-test.koshelek.app/<partner-name>
API Base URL (production)	https://api.koshelek.app/<partner-name>

Note that API Base URL is partner specific — that is, for partner with name name, API Base URL will be as follows:

• API Base URL (test): https://api-test.koshelek.app/name

• API Base URL (production): https://api.koshelek.app/name

The following table defines merchant identifiers involved in data exchange via Koshelek Pay API. Parameters specified in color are applicable to payment via Faster Payments System ("FPS", also known as "SBP" in Russian).

Parameter	Context	Description
brandName	General	Merchant brand name. Must match the name specified at merchant registration in SBP (so that customer would see the same name in bank app and in transactions). Must be provided to Koshelek at Pay API integration.
legalName	General	Merchant legal / individual entrepreneur name. Must be provided to Koshelek at Pay API integration.
Stores: storeId	General	Store ID. Assigned by Koshelek. Expected in merchant API requests and returned in responses. Sets up at POS.
partnerLogin	General if cash desk has online host	Merchant login (HTTP Basic Authentication). Assigned by Koshelek. Configurable at POS.
partnerPassword	General if cash desk has online host	Merchant password (HTTP Basic Authentication). Assigned by Koshelek. Configurable at POS.
Terminals: terminalId	General	POS ID. Assigned by merchant. Expected optionally in merchant's API requests, returned in responses. Involved in reconciliations. Configurable at POS.
legalId	SBP	Merchant legal name ID for SBP. Must be provided to Koshelek at Pay API integration.
merchantId	SBP	Merchant identifier for SBP. Merchant receives this ID from merchant's acquiring bank involved in SBP transactions (Recipient bank). Must be provided to Koshelek at Pay API integration. Mind strict one-to-one mapping between storeId and merchantId.
account	SBP	Merchant's legal name account number in recipient bank at which SBP payments will go. Must be provided to Koshelek at Pay API integration.
memberId	SBP	Merchant's partner bank (merchantId issuer) identifier for SBP. Must be provided to Koshelek at Pay API integration.
paymentPurpose	SBP	"Payment purpose" value applicable to transactions made from the linked SBP account. The value can be agreed between the merchant and Cardsmobile only once, or can be passed in every /checkout request.
subscriptionPurpose	SBP	"Account subscription purpose" for SBP transactions. Displayed in customer's bank app. Agreed between merchant and Koshelek at Pay API integration.
postbackUrl (deprecated)	General if cash desk has online host	URL used by the cash desk for accepting transaction status updates from the Koshelek Pay server.

API request authorization

API communication relies on HTTPS with HTTP Basic Authentication (RFC 7617) for request authorization. Request authorization credentials are passed in the Authorization HTTP header.

Minimum requirement for TLS version: 1.2.

Message encoding

Both request and response messages use the 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".