Retrieving the SBP payout feasibility check status

Returns the status of a previously created recipient details check via SBP.

Integration flow

Call the payout feasibility check and save the request_id from the 200 response.
Generate a signature over request_id and send a GET status request.
On processing, repeat the same GET request with the same request_id; do not create a new check for polling.
On success, use the received details when creating the payout. On error, handle error_message and correct the details before running a new check.

Polling interval

The recommended interval between status requests is at least 5 seconds.

URL

ProductionStage

GET https://api.pay.kvell.group/v1/orders/payout/sbp/check/status/{request_id}

GET https://api.pay.stage.kvell.group/v1/orders/payout/sbp/check/status/{request_id}

Request

Path parameters

Parameter	Type	Required	Description
`request_id`	string	Yes	Identifier from the response of the payout feasibility check method.

Headers

Name	Type	Required	Description
`X-Api-Key`	string	Yes	Shop identifier.
`X-Signature`	string	Yes	Request signature.

Building the signature

Concatenate X-Api-Key, request_id, and secret_key with no separators, compute SHA-256 of the resulting UTF-8 string, and pass the lowercase hex result in the X-Signature header.

SHA256(X-Api-Key + request_id + secret_key)

secret_key is found in the shop's settings. The order of the values must not be changed.

Example

curl --request GET \
  --url 'https://api.pay.stage.kvell.group/v1/orders/payout/sbp/check/status/check-req-20260811-0001' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000' \
  --header 'X-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'

Response

Select the HTTP code to see the example, response parameters, and recommended actions.

2004004034044225XX

Example 200 response (OK)

{
  "status": "success",
  "fio_nspk": "ИВАНОВ ИВАН ИВАНОВИЧ",
  "nspk_id": "A4073090444266160000040011200102",
  "error_message": "",
  "recipient_account": "40817***************"
}

Response parameters

Parameter	Type	Description
`status`	string	Check state. See possible values in «Check statuses».
`fio_nspk`	string \| null	Full name received from NSPK.
`nspk_id`	string \| null	NSPK link that may need to be passed in the payout request.
`error_message`	string \| null	Reason for rejection when `status: error`, received from the bank or NSPK. Possible values are listed below.
`recipient_account`	string \| null	Masked recipient account, if returned by the bank.

What to do next

On processing, repeat this GET request with the same request_id at an interval of at least 5 seconds.
On success, use the received details according to the requirements of the SBP payout method.
On error, handle error_message; do not create a payout with unverified details.

Example 400 response (Bad Request)

{
  "errors": [
    {
      "code": 20002,
      "message": "Invalid signature"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. `20002` in the example.
`errors[].message`	string	Description of why the request was rejected.

What to do next

Fix the cause from errors[].message. For 20002, check request_id, the order of values in the signature, and the shop's secret key.
Generate the correct X-Signature and safely retry the same GET request.

Example 403 response (Forbidden)

{
  "errors": [
    {
      "code": 20037,
      "message": "Access denied"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. `20037` in the example.
`errors[].message`	string	Description of the reason access was denied.

Example 404 response (Not Found)

{
  "errors": [
    {
      "code": 20006,
      "message": "Shop not found"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. `20006` in the example.
`errors[].message`	string	Description of the resource that was not found.

What to do next

Check X-Api-Key and the request environment.
Retry the request only after fixing the key or the environment URL.

Example 422 response (Unprocessable Entity)

{
  "errors": [
    {
      "code": 20098,
      "message": "x-signature: Field required"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of validation errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. `20098` for a field error.
`errors[].message`	string	Field and reason for the validation error.

What to do next

Fix the fields or headers indicated in errors[].message.
Generate the signature over the actual request_id and safely retry the GET request.

Example 5XX response (Internal Server Error)

{
  "errors": [
    {
      "code": 20000,
      "message": "Unknown error"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in «HTTP response errors».
`errors[].code`	integer	Error code. `20000` for an unknown error.
`errors[].message`	string	Description of the technical error.

What to do next

Safely retry the same GET request with the same request_id, X-Api-Key, and X-Signature.
If the error keeps recurring, contact KVELL support and provide the URL, request time, HTTP code, code, and message without the secret key or signature.

Check statuses

Status	Final	What to do
`processing`	No	The result isn't ready yet. Repeat this GET request with the same request_id; don't create a new check on every poll.
`success`	Yes	The check is complete. Use the received details when creating the payout.
`error`	Yes	The check failed; the payout cannot be sent using these details.

Reference data

Possible `error_message` values

KVELL returns in error_message the message received from the bank or NSPK. The list is not closed: banks and NSPK may add new messages or change the wording of existing ones.

`error_message` value	What it means and what to check
Недостаточно средств на счете {account} (Insufficient funds in account {account})	Insufficient funds.
Превышена разрешенная длина поля ustrd ("Описание платежа"). Разрешенная длина - {N} символов (Allowed length of the ustrd field ("Payment description") exceeded. Allowed length is {N} characters)	The payment description is too long.
Запрещены переводы на нерезидентов для данного клиента (Transfers to non-residents are prohibited for this client)	Transfers to non-residents are prohibited.
Значения параметров запроса не совпадают с данными предыдущего шага (Request parameter values do not match the data from the previous step)	Check the data and retry the payment.
Ошибка логики в СБП: Найден больше чем один Получатель (SBP logic error: More than one recipient found)	The recipient needs to contact their bank.
Ошибка логики в СБП: Не найден Получатель (SBP logic error: Recipient not found)	The recipient was not found in SBP.
Несовпадение ФИО получателя (Recipient full name mismatch)	Check the recipient's full name.
Ошибка логики в СБП: Получатель отказался от получения средств через СБП (SBP logic error: Recipient declined to receive funds via SBP)	The recipient needs to contact their bank.
Ошибка логики в СБП: Ограничения законодательства - уровень идентификации денежных средств недостаточен (SBP logic error: Legal restrictions — insufficient level of funds identification)	The recipient needs to contact their bank.
Ошибка логики в СБП: Получатель не дал согласие на получение средств через СБП (SBP logic error: Recipient did not consent to receiving funds via SBP)	The recipient needs to contact their bank.
Ошибка логики в СБП: OPKC_REJECT_COMMON (SBP logic error: OPKC_REJECT_COMMON)	System error.
Ошибка логики в СБП: EBD 20 has incorrect format (phone) (SBP logic error: EBD 20 has incorrect format (phone))	Check the recipient's phone format: it must be `79991111111`.
Ошибка логики в СБП: The transfer amount (44) exceeds the maximum allowed value (SBP logic error: The transfer amount (44) exceeds the maximum allowed value)	The transfer limit has been exceeded.
Ошибка логики в СБП: Счет Получателя не найден (SBP logic error: Recipient account not found)	The recipient needs to contact their bank.
Ошибка логики в СБП: OPKC_TIMEOUT (SBP logic error: OPKC_TIMEOUT)	This usually means NSPK did not receive a response from the recipient's bank (the recipient's bank was unavailable via SBP at the time of the operation).
Превышен лимит на сумму платежа в месяц. Сумма платежа не может быть выше ... руб. (Monthly payment amount limit exceeded. The payment amount cannot exceed ... RUB.)	The transfer limit has been exceeded.
Превышен лимит на сумму платежа на получателя в месяц. Сумма платежа не может быть выше 109991 руб (Monthly payment amount limit per recipient exceeded. The payment amount cannot exceed 109991 RUB)	The transfer limit has been exceeded.
OPKC_REJECT_SUSPECTED_FRAUD	Counteraction against mass fund withdrawals. The SBP OPKC is entitled to suspend SBP operations based on indicators of transfers made without the client's consent and risk-assessment models set by the Bank of Russia. Subject to monitoring and potential blocking are: — cases of detecting group SBP operations to a single recipient over a given period; — cases of detecting group SBP operations from a single sender's account over a given period; — cases of detecting mass fund withdrawal to a recipient's bank over a given period; — cases of detecting mass fund withdrawal from a sender's bank over a given period.
Описание платежа может содержать только символы из диапазонов U+0020 - U+007E, U+0410 - U+044F, U+0401, U+0451, U+2116 в Unicode (The payment description may only contain characters from the ranges U+0020–U+007E, U+0410–U+044F, U+0401, U+0451, U+2116 in Unicode)	Check what was passed in the payment description (purpose). For example, it may contain the letter Ё.

Recipient account mask

recipient_account depends on the recipient's bank and may be null or an empty string. The field is populated if the operation is performed through the Alfa-Bank or PSB Bank channel.

Within the bank channels used, the mask can be interpreted as follows:

Prefix	Description
`40817...`	Individual's current account. Usually used as an indicator of full recipient identification
`40820...`	Non-resident individual's account
`423...`	Individual's deposit account
`409...`	Account for e-money or virtual card operations. Does not confirm full recipient identification
`30232...`	Transit account for unsettled payments. Not the recipient's personal account and does not confirm full identification

An account with full identification can be recognized by the first three digits 408 — these are individuals' accounts. The next two digits specify who the account belongs to:

02 — individual entrepreneur accounts;
17 — resident individuals' current accounts;
20 — non-resident individuals' current accounts.

The mask does not guarantee the identification level

The recipient's bank may credit funds through a pooled account, return an e-wallet number, or not return recipient_account at all. Therefore, treat the field only as an additional indicator. The decision to allow or prohibit payouts to specific account types must be agreed upon for the specific acquiring bank. In particular, KVELL may be configured to prohibit payouts to accounts with the 409 prefix.

Retrieving the SBP payout feasibility check status

Integration flow

URL

Request

Path parameters

Headers

Building the signature

Example

Response

Check statuses

Reference data

Possible error_message values

Recipient account mask

Possible `error_message` values