API v1.0.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 before making appropriate changes to the software running on the merchant side.

Request list of available payment methods

HTTP method: POST

URL: /api/v1/merchant/availability-info/task

Description

Send your purchase details to Koshelek Pay server to create a task to populate the list of available payment methods.

Depending on 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. 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 the 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. Obtained from Koshelek TOTP Module deployed at your cash desk host (see 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 by 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.
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

Successful response, contains the 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 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 the 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

Successful response, contains parameters you should use to obtain the 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 be using in/merchant/availability-info/{availabilityInfoId}
timeout	Integer	Yes	Your waiting timeout before you can first call /merchant/availability-info/{availabilityInfoId}

Response body example

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

HTTP Status Code: 422

Request was not processed. Response body is a JSON object containing error description.

Get available payment methods

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 (a 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

Successful response.

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 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"
        }
    ]  
}

HTTP Status Code: 422

Request was not processed.

Response body is a JSON object containing 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. Obtained from Koshelek TOTP Module deployed at your cash desk host (see 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 by 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	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,
                            "quantity": 1,
                            "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

Successful response.

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 for 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
        }
}

HTTP Status Code: 422

Request was not processed.

Response body is a JSON object containing 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 Koshelek server can call to inform you of operation result. This option is preferred, as you'll be having the response right after 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 b. We advise you to follow option b only in case of technical unavailability to establish direct communication between Koshelek server and your server or cash desk software. POST request body: see Response body in option b. b. Implementation using polling

Respect 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 the 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 by 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

Successful response.

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. SBP — SBP.
slip	Object Slip	Depends on status value	Contains details for completed transaction. Returned either for completed payment via bank (status = accepted, rejected), or for completed refund (status = refunded, partial_refunded).
refStatus	Enum	No	Status for 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.

Available errorCode values

1. For payment transaction:

Value	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. For refund transaction:

Value	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.)

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

Request was not processed.

Response body is a JSON object containing error description.

Send payment receipt

HTTP method: POST

URL: /api/v1/merchant/transaction/receipt

Description

Use this method to send fiscal receipt for completed transaction. The receipt information will be displayed to customer on their Koshelek App screen.

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 by 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 a "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",
                "discountAmount": "100",
                "subTotalAmount": "14345",
                "items": [
                        {  
                            "name": "Item 1",
                            "article": "1111111",
                            "price": 10000,
                            "quantity": 1,
                            "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

Successful response.

Response body is empty.

HTTP Status Code: 422

Request was not processed.

Response body is a JSON object containing 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 cancel 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 by 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 cancel.

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

Successful response.

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	Cancel 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 cancel request processing: new canceled pending rejected accepted refunding refunded partial_refunded none
slip	Object Slip	Depends on status value	Contains details for 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",
        "totalAmount": 15000
        }
}

HTTP Status Code: 422

Request was not processed.

Response body is a JSON object containing error description.

Refund payment

HTTP method: POST

URL: /api/v1/merchant/transaction/refund

Description

Use this request to initiate refund for completed payment transaction.

Request parameters

Request header

Parameter	Type	Mandatory	Description
token	String	Yes	Consists of cashFingerPrint and TOTP password. Obtained from Koshelek TOTP Module deployed at your cash desk host (see 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 by 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,
    "items": [
        {  
           "name": "Item 1",
           "price": 10000,
           "quantity": 1,
           "totalAmount": 1900,
           "discount": 100,
           "subTotalAmount": 2000,
           "tax": "vat10"
        },
        {  
           "name": "Item 2",
           "price": 12345,
           "quantity": 1,
           "totalAmount": 12345,
           "tax": "vat20"
        }
    ]
}

Response parameters

HTTP Status Code: 200

Successful response.

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 for completed transaction. Returned for completed payment via bank (status = accepted, rejected).
errorCode	Enum	No	Code of 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 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.)

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",
        "totalAmount": 15000
        }
}

HTTP Status Code: 422

Request was not processed.

Response body is a JSON object containing error description.