API v1.2.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:

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

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

Since Pay API v1.2.0 and onwards, the asynchronous processing of Request list of available payment methods and associated Get available payment methods request are no longer supported for new integrations.

The combination of these two methods implement obtaining the list of available payment methods in asynchronous manner, which is now deprecated. Instead, do use synchronous flow (with HTTP status code 200).

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 (deprecated). 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
token	String	Yes	Consists of cashFingerPrint and TOTP password. The value is obtained from Koshelek TOTP Module deployed in your cash desk host (refer to Koshelek TOTP Module).

Request header example

token: SW50ZWwoUikgQ29yZShUTSkgaTUtNzIwMFUgQ1BVIEAgMi41MEdIejtDUFUWO1RpbWk7TU1HNVMwMDAwMDEwNzc5TFAwMzFaOzE2MTcyNzYxNzk2MjA7MTkyLjE2OC4xLjEwMztVU0IgUm9vdCBIdWIgKFVTQiAzLjApI1VTQiBDb21wb3NpdGUgRGV2aWNlI1hpYW9NaSBVU0IgMi4wIFdlYmNhbSNJbnRLbChSKSBXaXJLbGVzcyBCbHVLdG9vdGgoUikjRUxBTiBXQkYgRmluZ2VycHJpbnQgU2Vuc29yI1VTQiBJbnB1dCBEZXZpY2UjSElELWNvbXBsaWFudCBtb3VzZQ==967

Request body

Request body is a JSON object of the following structure:

Field	Type	Mandatory	Description
requestId	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 requestId parameter (idempotency is provided).
cardSession	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).
storeId	String	Yes	Merchant's store ID (GUID, 36 characters).
terminalId		Yes	Cash desk (terminal) ID (up to 256 characters).
checkoutInvoice	Object CheckoutInvoice	Yes	Invoice data (refer to the CheckoutInvoice object).
user	Object User	Yes	Customer data.

Request body example

{
    "requestID": "1624931549080"
    "cardsession": "123456",
    "storeId": "bb99e4c8-0a6e-4b60-8aeb-fe2345f1b99",
    "terminalId": "mip9e26ay3z2s0oh",
    "checkoutInvoice": {
        "orderId": "ac99e4c8-1a7e-4b60-8aeb-fe10110f1b99",
        "totalAmount": 20,
        "discountAmount": 5,
        "subTotalAmount": 20,
        "items": [
            {
                "name": "testName",
                "article": "1111111",
                "price": null,
                "quantity": 1,
                "totalAmount": 20,
                "discountAmount": 5,
                "subTotalAmount": 100,
                "tax": "none"
            }
        ],
    },
    "user": {
        "loyaltyId": "000022"
    },
}

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
koshelekPayIsDefault	Boolean	Yes	Flag for automatic selection of Koshelek Pay as the default payment option at the checkout. If true, then paymentTypeAvailabilityInfoList will contain at least one available payment method (available= true).
paymentTypeAvailabilityInfoList	Array of PaymentTypeAvailabilityInfo	Yes	Array containing a list of available payment methods.

Response body example

{
    "koshelekPayIsDefault": true,
    "paymentTypeAvailabilityInfoList": [
        {
            "paymentType": "SBP",
            "available": true,
            "message": ""
        },
        {
            "paymentType": "DOLYAME",
            "available": false,
            "message": "Unavailable"
        }
    ]  
}

HTTP Status Code: 201 (deprecated)

The request is processed. The response contains parameters you should use to obtain a list of available payment methods (asynchronous mode).

Response header:

Location: /api/v1/merchant/availability-info/{availabilityInfoId}

Response body is a JSON object of the following structure:

Field	Type	Mandatory	Description
availabilityInfoId	String	Yes	An ID you'll use in/merchant/availability-info/{availabilityInfoId}
timeout	Integer	Yes	Your waiting timeout before you should call /merchant/availability-info/{availabilityInfoId}

Response body example

 {
   "availabilityInfoId": "ecda679e-f5ab-4250-b622-2a429d714b21",
   "timeout": 350
 }

HTTP Status Code: 422

An error occurred. Response body is a JSON object containing the error description.

Get available payment methods (deprecated)

Since Pay API v1.2.0 and onwards, the asynchronous processing of Request list of available payment methods and associated Get available payment methods request are no longer supported for new integrations.

The combination of these two methods implement obtaining the list of available payment methods in asynchronous manner, which is now deprecated. Instead, do use synchronous flow (with HTTP Status Code 200).

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
availabilityInfoId	String	Yes	ID received in request.
computationComplete	Boolean	Yes	Indicates completeness of request processing: true — completed; false — not completed.
pollingTimeout	Long	Yes	Instruction from server: make re-request after specified time (in milliseconds). Returned if computationComplete = false.
koshelekPayIsDefault	Boolean	Yes	Flag for automatic selection of Koshelek Pay as the default payment option at the checkout. If true, then paymentTypeAvailabilityInfoList will contain at least one available payment method (available= true).
paymentTypeAvailabilityInfoList	Array of PaymentTypeAvailabilityInfo	Yes	List of available payment methods.

Response body example

{
    "availabilityInfoId": "ecda679e-f5ab-4250-b622-2a429d714b21",
    "computationComplete": true,
    "koshelekPayIsDefault": true,
    "paymentTypeAvailabilityInfoList": [
        {
            "paymentType": "SBP",
            "available": true,
            "message": ""
        },
        {
            "paymentType": "DOLYAME",
            "available": false,
            "message": "Unavailable due to low credit rating"
        }
    ]  
}

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
token	String	Yes	Consists of cashFingerPrint and TOTP password. The value is obtained from Koshelek TOTP Module deployed at your cash desk host (refer to Koshelek TOTP Module).

Request header example

token: SW50ZWwoUikgQ29yZShUTSkgaTUtNzIwMFUgQ1BVIEAgMi41MEdIejtDUFUWO1RpbWk7TU1HNVMwMDAwMDEwNzc5TFAwMzFaOzE2MTcyNzYxNzk2MjA7MTkyLjE2OC4xLjEwMztVU0IgUm9vdCBIdWIgKFVTQiAzLjApI1VTQiBDb21wb3NpdGUgRGV2aWNlI1hpYW9NaSBVU0IgMi4wIFdlYmNhbSNJbnRLbChSKSBXaXJLbGVzcyBCbHVLdG9vdGgoUikjRUxBTiBXQkYgRmluZ2VycHJpbnQgU2Vuc29yI1VTQiBJbnB1dCBEZXZpY2UjSElELWNvbXBsaWFudCBtb3VzZQ==967

Request body

Request body is a JSON object of the following structure:

Field	Type	Mandatory	Description
requestId	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 requestId parameter (idempotency is provided.)
cardSession	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).
storeId	String	Yes	Merchant's store ID (GUID, 36 characters).
terminalId	String	Yes	Cash desk (terminal) ID (up to 256 characters).
checkoutInvoice	Object CheckoutInvoice	Yes	Invoice data.
user	Object User	Yes	Customer data.
paymentMethods	Array of PaymentMethod	Yes	Objects array defining available payment methods.

Request example:

Request body example

{
    "requestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
    "cardSession": "A1G97N",
    "storeId": "bb99e4c8-0a6e-4b60-8aeb-fe2345f1b99",
    "terminalId": "mip9e26ay3z2s0oh",
    "checkoutInvoice": {
                "orderId": "12345",
                "totalAmount": "14245",
                "discountAmount": "100",
                "subTotalAmount": "14345",
                "items": [
                        {  
                            "name": "Item 1",
                            "article": "1111111",
                            "price": 10000,
                            "currency": "RUB",
                            "quantity": 1125.0,
                            measure: "GRAM",
                            "totalAmount": 1900,
                            "discountAmount": 100,
                            "subTotalAmount": 2000,
                            "tax": "vat10"
                        },
                        {  
                            "name": "Item 2",
                            "article": "2222222",
                            "price": 12345,
                            "quantity": 1,
                            "totalAmount": 12345,
                            "discountAmount": 15,
                            "subTotalAmount": 3000,
                            "tax": "vat20"
                        }
                        ]
                },
    "user": {
                "loyaltyId": "1234567891011"
            },
    "paymentMethods": [
        {
         "type": "SBP"
        }
    ]
}

Response parameters

HTTP Status Code: 200

The response is processed.

Response body is a JSON object of the following structure:

Field	Type	Mandatory	Description
requestId	String	Yes	Unique request ID.
transactionId	String	Yes	Transaction ID.
status	Enum	Yes	Transaction status: new canceled pending rejected accepted refunding refunded partial_refunded
slip	Object Slip	Depends on status value	Contains details of the completed transaction. Returned either for completed payment via bank (statuses: accepted, rejected), or for completed refund (statuses: refunded, partial_refunded).

Response body example

{
  "requestId": "314b0613-ae21-438c-b538-6b965e85d644",
  "transactionId": "f9a59682-3d05-4af6-8308-2c1f1665d733",
  "status": "new",
  "slip": {
        "id": "d95d9f7d-cea2-47c0-b9b5-4e7ad3ee4c63",
        "paymentTransactionId": "48f62a99-50a2-4e0c-a883-4be0a7c62dd7",
        "paymentType": "DOLYAME",
        "terminalId": "20210510T120700",
        "storeId": "KOSHELEK-42",
        "orderId": "9d913e76-24d9-468d-6c6d-2a41bcfb8d81",
        "merchantId": "MA0000103685",
        "operationDateTime": "2022-01-19T11:56:34.323Z",
        "totalAmount": 15000,
        "currency": "RUB"
        }
}

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:

1. Initial call: make one after 250 ms at the soonest but no later than 500 ms.

2. All subsequent calls can be made with a delay of at least 250 ms between them.

3. 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
requestId	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 requestId parameter (idempotency is provided).
transactionId	String	No	ID for payment transaction (GUID, 36 characters). Omitted if refTransactionId is passed.
refTransactionId	String	No	ID for payment cancel transaction (GUID, 36 characters). Omitted if transactionId is passed.

Request body example

{
    "requestId": "ab182f20-9c5a-11ea-ab12-0800200c9a66",
    "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66"
}

Response parameters

HTTP Status Code: 200

The request is processed.

Response body is a JSON object of the following structure:

Field	Type	Mandatory	Description
requestId	String	Yes	Unique request ID.
transactionId	String	Yes	ID for payment transaction.
refTransactionId	String	No	ID for payment cancel transaction.
status	Enum	Yes	Transaction status: new canceled pending rejected accepted refunding refunded partial_refunded — or void, if transactionId specified in request is not found.
paymentGroup	Enum	Yes	Payment category: INSTALLMENT — installment loans. SBP — Faster Payments System (SBP).
paymentProvider	Enum	Yes	Payment provider: DOLYAME — Dolyame.
slip	Object Slip	Depends on the status value	Contains details of completed transaction. Returned either for completed payment via bank (status = accepted, rejected), or for completed refund (status = refunded, partial_refunded).
refStatus	Enum	No	Status of payment cancel transaction: new — initial status. rejected — cancel rejected, refund not fulfilled. accepted — cancel accepted.
errorCode	Enum	No	Code of error occurred during payment or refund transaction. Returned only if status or refStatus = rejected. See available values below.

Possible errorCode values

1. For payment transaction:

Value	Description
NOT_ENOUGH_LIMIT_TO_PAY	Transaction limit is exceeded.
TOTAL_AMOUNT_IS_TOO_SMALL	Transaction amount is below the limit (equals 4 rubles).
EXTERNAL_PROVIDER_ERROR	General error code of payment provider.
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.)

2. For refund transaction:

Value	Description
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.
EXTERNAL_PROVIDER_ERROR	General error code of 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).

Response body example

{
    "requestId": "ab182f20-9c5a-11ea-ab12-0800200c9a66",
    "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66",
    "status": "pending"
    "paymentGroup": "INSTALLMENT",
    "paymentProvider": "DOLYAME"
 }

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
requestId	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 requestId parameter (idempotency is provided).
transactionId	String	Yes	Payment transaction ID (GUID, 36 characters).
storeId	String	Yes	Merchant's store ID (GUID, 36 characters).
terminalId	String	Yes	Cash desk (terminal) ID (up to 256 characters).
invoice	Object Invoice	Yes	Invoice data.
meta	Object	No	Object for extra fields (e.g. discounts, bonuses etc.) in the "key-value" format.

Request body example

{
    "requestId": "045b22e0-9c5b-11ea-ab12-0800200c9a66",
    "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66",
    "storeId": "bb99e4c8-0a6e-4b60-8aeb-fe2345f1b99",
    "terminalId": "mip9e26ay3z2s0oh",
    "invoice": {
                "orderId": "12345",
                "receiptId": "6789",
                "merchantName": "Merchant Name",
                "merchantAddress": "Merchant address",
                "inn": "001234567891",
                "dateTime": "2020-05-20T20:50:00+03:00",
                "shift": "5",
                "cashier": "John Thomson",
                "taxation": "osn",
                "kktRegNumber": "0004147503041443",
                "fnNumber": "9280440300387752",
                "fdNumber": "0000010272",
                "fpd": "2374313442",
                "website": "nalog.ru",
                "receiptType": "debit",
                "qr": "t=20200520T2050&s=859.00&fn=9280440300387752&i=10272&fp=2374313442&n=1",
                "totalAmount": "14245",
                "currency": "RUB",
                "discountAmount": "100",
                "subTotalAmount": "14345",
                "items": [
                        {  
                            "name": "Item 1",
                            "article": "1111111",
                            "price": 10000,
                            "currency": "RUB",
                            "quantity": 2.0,
                            "measure": "GRAM",
                            "totalAmount": 1900,
                            "discountAmount": 100,
                            "subTotalAmount": 2000,
                            "tax": "vat10"
                        },
                        {  
                            "name": "Item 2",
                            "article": "2222222",
                            "price": 12345,
                            "quantity": 1,
                            "totalAmount": 12345,
                            "discountAmount": 15,
                            "subTotalAmount": 3000,
                            "tax": "vat20"
                        }
                        ]
                }
}

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
requestId	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 requestId parameter (idempotency is provided).
storeId	String	Yes	Merchant's store ID (GUID, 36 characters).
terminalId	String	Yes	Cash desk (terminal) ID (up to 256 characters).
transactionId	String	Yes	Payment transaction ID subject for cancellation.

Request body example

{
    "requestId": "f1847360-b3c5-11ea-8b6e-0800200c9a66",
    "storeId": "bb99e4c8-0a6e-4b60-8aeb-fe2345f1b99",
    "terminalId": "mip9e26ay3z2s0oh",
    "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66"
}

Response parameters

HTTP Status Code: 200

The request is processed.

Response body is a JSON object of the following structure:

Field	Type	Mandatory	Description
requestId	String	Yes	Unique request ID.
refTransactionId	String	Yes	Cancel transaction ID.
refStatus	Enum	Yes	Cancellation transaction status: new — initial status. rejected — cancellation rejected (see Usage Scenarios for possible reject reasons). accepted — cancellation accepted.
transactionId	String	Yes	Payment transaction ID.
status	Enum	Yes	Payment transaction status after cancellation request processing: new canceled pending rejected accepted refunding refunded partial_refunded none
slip	Object Slip	Depends on status value	Contains details of the completed transaction. Returned either for completed payment via bank (status = accepted, rejected), or for completed refund (status = refunded, partial_refunded).

Response body example

{
  "requestId": "requestId",
  "refTransactionId": "59ab316c-4de4-4e0d-8d07-448b2c7f25a7",
  "refStatus": "accepted",
  "transactionId": "6b66835f-a82a-4385-bd98-e9a5047e88fa",
  "status": "canceled",
  "slip": {
        "id": "d95d9f7d-cea2-47c0-b9b5-4e7ad3ee4c63",
        "paymentTransactionId": "48f62a99-50a2-4e0c-a883-4be0a7c62dd7",
        "paymentType": "DOLYAME",
        "terminalId": "20210510T120700",
        "storeId": "KOSHELEK-42",
        "orderId": "9d913e76-24d9-468d-6c6d-2a41bcfb8d81",
        "merchantId": "MA0000103685",
        "operationDateTime": "2022-01-19T11:56:34.323Z",
        "operationId": "e1df75fe-eb80-428e-96f6-032acefcb995",
        "totalAmount": 15000
        }
}

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
token	String	Yes	Consists of a TOTP password and cashFingerPrint obtained from Koshelek TOTP Module deployed at your cash desk host (refer to Koshelek TOTP Module).

Request header example

token: SW50ZWwoUikgQ29yZShUTSkgaTUtNzIwMFUgQ1BVIEAgMi41MEdIejtDUFUWO1RpbWk7TU1HNVMwMDAwMDEwNzc5TFAwMzFaOzE2MTcyNzYxNzk2MjA7MTkyLjE2OC4xLjEwMztVU0IgUm9vdCBIdWIgKFVTQiAzLjApI1VTQiBDb21wb3NpdGUgRGV2aWNlI1hpYW9NaSBVU0IgMi4wIFdlYmNhbSNJbnRLbChSKSBXaXJLbGVzcyBCbHVLdG9vdGgoUikjRUxBTiBXQkYgRmluZ2VycHJpbnQgU2Vuc29yI1VTQiBJbnB1dCBEZXZpY2UjSElELWNvbXBsaWFudCBtb3VzZQ==967

Request body

Request body is a JSON object of the following structure:

Field	Type	Mandatory	Description
requestId	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 requestId parameter (idempotency is provided).
storeId	String	Yes	Merchant's store ID (GUID, 36 characters).
terminalId	String	Yes	Cash desk (terminal) ID (up to 256 characters).
transactionId	String	Yes	ID of payment transaction subject for refund (GUID, 36 characters).
refundAmount	Number	Yes	Refund amount in kopecks. Must not exceed payment amount. Only positive number.
items	Array of Item	Yes	Objects array defining commodity items being returned.

Request body example

{
    "requestId": "f1847360-b3c5-11ea-8b6e-0800200c9a66",
    "transactionId": "9dcc19d0-9c5a-11ea-ab12-0800200c9a66",
    "storeId": "bb99e4c8-0a6e-4b60-8aeb-fe2345f1b99",
    "terminalId": "mip9e26ay3z2s0oh",
    "refundAmount": 14245,
    "currency": "RUB",
    "items": [
        {  
           "name": "Item 1",
           "price": 10000,
           "currency": "RUB",
           "quantity": 1125.0,
           "measure": "GRAM",
           "totalAmount": 1900,
           "discountAmount": 100,
           "subTotalAmount": 2000,
           "tax": "vat10"
        },
        {  
           "name": "Item 2",
           "price": 12345,
           "quantity": 1.0,
           "totalAmount": 12345,
           "tax": "vat20"
        }
    ]
}

Response parameters

HTTP Status Code: 200

The request is processed.

Response body is a JSON object of the following structure:

Field	Type	Mandatory	Description
requestId	String	Yes	Unique request ID.
refTransactionId	String	Yes	Refund transaction ID.
refStatus	Enum	Yes	Refund transaction status: new — initial status. rejected — refund rejected. accepted — refund accepted.
transactionId	String	Yes	Payment transaction ID.
status	Enum	Yes	Payment transaction ID status after refund request processing: new canceled pending rejected accepted refunding refunded partial_refunded none
slip	Object Slip	No	Contains details of completed transaction. Returned either for completed payment via bank (status = accepted, rejected), or for completed refund (status = refunded, partial_refunded).
errorCode	Enum	No	Code of an error occurred during refund transaction. Returned only if refStatus = rejected. See available values below.

Available errorCode values

Value	Description
PAYMENT_TRANSACTION_IS_NOT_PAID	Refund rejected as the transaction with this transactionId is not completed (and amounts were 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 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 one declared in payment transaction with this transactionId.
EXTERNAL_PROVIDER_ERROR	General error code of 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).

Response body example

{
  "requestId": "314b0613-ae21-438c-b538-6b965e85d644",
  "refTransactionId": "665857e3-25ca-4bd2-b2ec-87c994eff47a",
  "refStatus": "accepted",
  "transactionId": "f9a59682-3d05-4af6-8308-2c1f1665d733",
  "status": "refunded",
  "slip": {
        "id": "d95d9f7d-cea2-47c0-b9b5-4e7ad3ee4c63",
        "paymentTransactionId": "48f62a99-50a2-4e0c-a883-4be0a7c62dd7",
        "paymentType": "DOLYAME",
        "terminalId": "20210510T120700",
        "storeId": "KOSHELEK-42",
        "orderId": "9d913e76-24d9-468d-6c6d-2a41bcfb8d81",
        "merchantId": "MA0000103685",
        "operationDateTime": "2022-01-19T11:56:34.323Z",
        "operationId": "e1df75fe-eb80-428e-96f6-032acefcb995",
        "totalAmount": 15000,
        "currency": "RUB"
        }
}

HTTP Status Code: 422

An error occurred.

Response body is a JSON object containing the error description.