Pay API v1.1.0

In-store payments with Koshelek Pay API.

General information

This guide is intended for retail and service outlet companies (Merchants) that contemplate to enable in-store payments with service “Koshelek Pay”.

Pay API versions

Pay API updates can be tracked here: Changelog.
New merchants integrate to the most current Pay API version.
Payment providers “SBP” and “Dolyame” are available from Pay API 0.9.0.

Updates: Pay API v1.0.0 → v1.1.0

Refund payment

Request body: added parameter currency.

Object item

Added parameters measure, currency.
Parameter quantity: added usage examples.

Object slip

Added parameter currency.
Parameter operationId: updated description (parameter value is assigned by payment provider upon return).

Object checkoutInvoice

Added parameter currency.

Object invoice

Added parameter currency.

Connecting to API

Koshelek Pay API is provided by a dedicated Koshelek host. API consumers are merchant’s cash desk software and data center hosts. 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/
API Base URL (production)	https://api.koshelek.app/

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

Important:

When implementing a service that interacts with Pay API, partner must ensure these parameters to be configurable (either through a dedicated configuration file or otherwise):

Login
Password
API Base URL (test, production)
Stores:storeId (see parameter description below)
Terminals:terminalId (see parameter description below

API credentials and identifiers

The following table defines merchant identifiers involved in data exchange via Koshelek Pay API. Parameters specified in color are applicable to payments via Faster Payments System (“FPS”, most commonly known as “SBP” in Russia):

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` 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 requests to `postbackUrl` (HTTP Basic Authentication).
`partnerPassword`	General if cash desk has online host	Password to authenticate requests to `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 must be unique within one `storeId` (store or service point).
`legalId`	SBP	Merchant legal name ID for SBP. Issued by the recipient bank upon merchant onboarding to SBP. The merchant must present this parameter to Koshelek team prior to API integration.
`merchantId`	SBP	Merchant identifier for SPB. 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`	SBP	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`	SBP	Merchant’s partner bank identifier for SBP. The merchant must present this parameter to the Koshelek team prior to API integration.
`paymentPurpose`	SBP	“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 .../merchant/checkout` request.
`subscriptionPurpose`	SBP	“Account subscription purpose” value agreed between the merchant and the Koshelek team prior to API integration.

Authorization

The HTTPS protocol is used. HTTP Basic Authentication (RFC 7617) mechanism should be used for API requests authorization. Credentials for authorization are transferred in the Authorization HTTP header.

Note

Minimum TLS version: 1.2.

Encoding

Both API requests and responses should 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.

HTTP codes

🟢 HTTP: 200

Successful API response will return data as described in API specification, along with HTTP response code 200.

Field `errorCode`

In particular transaction scenarios, the HTTP 200 response code may come along with the error message. If so, the error message is communicated in the errorCode field of the response body. AvailableerrorCode values are described below.

1. Payment transactions:

errorCode	Description
`NOT_ENOUGH_LIMIT_TO_PAY`	Transaction limit has exceeded.
`TOTAL_AMOUNT_IS_TOO_SMALL`	Transaction amount is below the limit (equals 4 rubles).
`EXTERNAL_PROVIDER_ERROR`	General error code for payment provider.
`SUBSCRIPTION_IS_NOT_FOUND`	No subscribed account found (applicable to SBP payments from subscribed account).
`PAYMENT_DECLINED_BY_EXTERNAL_PROVIDER`	Payment declined by bank (applicable to SBP transactions from subscribed account).

2. Refund transactions:

errorCode	Description
`PAYMENT_TRANSACTION_IS_NOT_PAID`	Refund rejected due to transaction with this `transactionId` is not completed (and amounts were not written off).
`TERMINAL_STATE_OF_PAYMENT_TRANSACTION`	Refund rejected due to either of the following reasons: Transaction was canceled before (debiting was not performed). Transaction was rejected earlier by payment provider (debiting was not performed). Full refund has already been performed.
`PAYMENT_TRANSACTION_IS_BEING_REFUNDED_ALREADY`	Refund rejected due to there is an ongoing refund already. Wait until a previous refund transaction with `refTransactionId` is completed.
`REQUESTED_REFUND_AMOUNT_IS_GREATER_THAN_AVAILABLE`	Refund rejected due to requested refund amount exceeds one declared in payment transaction with this `transactionId`.
`EXTERNAL_PROVIDER_ERROR`	General error code for payment provider.
`UNEXPECTED_REFUND_AMOUNT_LEFT_FROM_EXTERNAL_PROVIDER`	Refund rejected due to payment transaction with this `transactionId` was not completed and debiting was not performed.
`PAYMENT_ORDER_IS_NOT_FOUND`	No bank transfer order found in merchant’s bank upon refund (applicable to SBP transactions).

🔴 HTTP: 422

Indicates API request processing error. The response contains 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	Description
`code`	String	Error code (see below).
`details`	String	Error description (optional).

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.