Перейти к содержанию

Pay API v1.2.1

In-store payments with Koshelek Pay.

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.2.0 → v1.2.1

Object invoice

  • Parameter taxAmount is no longer mandatory.

Connecting to API

Pay API is provided by a dedicated Koshelek host. API consumers are merchant’s cash desk software and data center hosts.

To integrate with 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:

Parameter Value
API Base URL (test) https://api-test.koshelek.app/name
API Base URL (production) https://api.koshelek.app/name

API credentials and identifiers

The following table defines merchant identifiers involved in data exchange via Pay API. Parameters marked with “SBP” in the Context column are related to payments via Faster Payments System (“FPS”, most commonly known as “SBP” in Russia).

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 (as storeId).
  • 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 (as terminalId).
  • 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.
  • Must be provided to Koshelek at Pay API integration.
  • Mind strict 1:1 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 which manages merchant’s account) 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 POST /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.

    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 code Description
    200 Successful API response will return data as described in API specification, along with HTTP response code 200.
    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 Mandatory Description
    code String Yes Error code (see below).
    details String No Error description.

    Error codes

    Code Description Tips for cash desk operator
    EXTERNAL_PROVIDER_ERROR General error code for payment provider. Попробуйте ещё раз или выберите другой способ оплаты
    UNKNOWN_SESSION_ID cardSession not found or invalid. Повторно отсканируйте карту лояльности и повторите
    UNKNOWN_TRANSACTION_ID transactionId not found. Попробуйте ещё раз или выберите другой способ оплаты
    UNKNOWN_PARTNER_ID merchant not found. Техническая ошибка. Обратитесь к администратору, т.к. магазин не найден.
    WRONG_TRANSACTION_STATE_CHANGE Request transaction status transit is not possible. Попробуйте ещё раз или выберите другой способ оплаты
    PAYMENT_TRANSACTION_IS_NOT_PAID There is no fulfilled payment for this payment transaction. Попробуйте ещё раз через "X" минут или обратитесь к администратору
    (Note: “X” must be configurable)
    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. Оплата уже проведена
    NOT_ENOUGH_LIMIT_TO_PAY Transaction limit is exceeded. Слишком большая сумма чека оплаты Долями. Попробуйте оплату СБП или смешанную оплату.
    TOTAL_AMOUNT_IS_TOO_SMALL Transaction amount is below the limit (equals 4 rubles). Сумма чека слишком маленькая
    SUBSCRIPTION_IS_NOT_FOUND No subscribed account found (applicable to SBP transactions from the subscribed account). Привязка счёта СБП не найдена. Попробуйте оплату Долями.
    PAYMENT_DECLINED_BY_EXTERNAL_PROVIDER Payment declined by bank (applicable to SBP transactions from the subscribed account). Проверьте достаточность средств или попробуйте оплату Долями
    PAYMENT_TRANSACTION_IS_NOT_PAID Refund rejected as transaction with this transactionId is not completed (and amount was not written off). Покупка не найдена. Обратитесь к администратору.
    TERMINAL_STATE_OF_PAYMENT_TRANSACTION Refund rejected due to one of the following reasons:
    • Transaction has been canceled before (debiting was not performed);
    • Transaction has been rejected earlier by the payment provider (debiting was not performed);
    • Full refund has already been performed.
    		 Возврат уже выполнен
    PAYMENT_TRANSACTION_IS_BEING_REFUNDED_ALREADY Refund rejected as there is an ongoing refund already. Wait until the previous refund transaction with this refTransactionId is completed. Дождитесь результата возврата
    REQUESTED_REFUND_AMOUNT_IS_GREATER_THAN_AVAILABLE Refund rejected as the requested refund amount exceeds the one declared in payment transaction with this transactionId. Сумма возврата превышает сумму оплаты
    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). Возврат отклонён, т.к. магазин не поддерживает возвраты. Обратитесь к администратору.