Checking payout feasibility via SBP

Method for checking the recipient's details before a payout via SBP.

Check with currency conversion

If the intended payout amount is in a currency other than the shop's currency, and you need to see the rate and the converted amount in advance — use «SBP payout feasibility check with conversion».

Integration flow

Get bank_id from the list of SBP banks.
Build a request with the phone number, the recipient's bank, and the payout amount.
Save request_id from the 200 response. This response only means that the check request has been registered.
Poll the check status with the same request_id until you receive success or error. If processing, keep polling without creating a new check.

When a preliminary check is needed

A check is needed if, before creating a payout, you need to make sure that the selected bank can accept a transfer to the given phone number, obtain the full name from NSPK, or verify that it matches.

URL

ProductionStage

POST https://api.pay.kvell.group/v1/orders/payout/sbp/check

POST https://api.pay.stage.kvell.group/v1/orders/payout/sbp/check

Request

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, phone, bank_id, and secret_key with no separators, compute SHA-256 of the resulting UTF-8-encoded string, and pass the lowercase hash in the X-Signature header.

SHA256(X-Api-Key + phone + bank_id + secret_key)

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

Request body

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount of the intended payout in kopecks. For example, `15000` is 150 ₽.
`bank_id`	string	Yes	Recipient bank identifier from the list of SBP banks.
`bank_bic`	string	Conditional	BIC from the bank list. Required if the acquiring bank requires it. Check with your account manager.
`phone`	string	Yes	Recipient's phone number: 11 digits, without `+`, spaces, brackets, or separators. Example: `79999999999`.
`fio`	string	No	Recipient's full name. Used together with `fio_check` to verify a match against NSPK data.
`fio_check`	boolean	No	`true` — check that `fio` matches the full name obtained from NSPK.
`description`	string	No	Purpose of the intended payout. Defaults to "выплата" ("payout"). The resulting string together with the shop's prefix must not exceed 110 characters.

Full name check

fio and fio_check can be omitted; in that case, the customer's full name will be returned when getting the payout feasibility status.

If you pass fio_check: true, use the full name in the same form as it is registered with the recipient's bank. Some banking channels reject the characters Ё/ё even before the match check. If you get a format error, pass the variant with Е/е.

Example

JSONcURL

{
  "amount": 15000,
  "bank_id": "100100000014",
  "fio": "Иванов Иван Иванович",
  "fio_check": true,
  "phone": "79999999999",
  "description": "Выплата по договору 42"
}

curl --request POST \
  --url 'https://api.pay.stage.kvell.group/v1/orders/payout/sbp/check' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000' \
  --header 'X-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef' \
  --data '{"amount":15000,"bank_id":"100100000014","fio":"Иванов Иван Иванович","fio_check":true,"phone":"79999999999","description":"Выплата по договору 42"}'

Response

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

2004004034044225XX

Example 200 (OK) response

{
  "request_id": "check-req-20260811-0001"
}

Response parameters

Parameter	Type	Description
`request_id`	string	Identifier of the registered check. Used to get its status.

What to do next

Save request_id.
Call the check status method.

Example 400 (Bad Request) response

{
  "errors": [
    {
      "code": 20002,
      "message": "Неверная подпись"
    }
  ]
}

Example bank error

{
  "errors": [
    {
      "code": 20099,
      "message": "1706: Банк с RbankID = 100000000118 не найден!"
    }
  ]
}

Response parameters

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

What to do next

For 20002, check the order of values in the signature and the shop's secret key.
For 20099, fix the cause given in message.
If phone or bank_id changed, recompute X-Signature, then retry the request.

Example 403 (Forbidden) response

{
  "errors": [
    {
      "code": 20037,
      "message": "Доступ запрещен"
    }
  ]
}

Response parameters

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

Example 404 (Not Found) response

{
  "errors": [
    {
      "code": 20006,
      "message": "Магазин не найден"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in the «HTTP response errors» section.
`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 (Unprocessable Entity) response

{
  "errors": [
    {
      "code": 20098,
      "message": "amount: Field required"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of validation errors. Codes and handling recommendations are given in the «HTTP response errors» section.
`errors[].code`	integer	Error code. Can be field error `20098` or dependent service code `20099`.
`errors[].message`	string	Reason for the validation error.

What to do next

For 20098, fix the fields listed in errors[].message.
For 20099, check the request parameters; if the cause is unclear, contact KVELL support.
If phone or bank_id changed, recompute X-Signature.
Send the corrected request and save request_id from the 200 response.

Example 5XX (Internal Server Error) response

{
  "errors": [
    {
      "code": 20000,
      "message": "Неизвестная ошибка"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and handling recommendations are given in the «HTTP response errors» section.
`errors[].code`	integer	Technical error code. Can be `20000` or dependent service code `20099`.
`errors[].message`	string	Description of the technical error.

5XX, timeout, and connection drop

A technical error does not mean the details check finished with business status error. The request may have been registered even if the client did not receive request_id. This method does not create a payout or a financial transaction.

What to do next

If request_id was received earlier, request the status with the same identifier.
If request_id was not received, try repeating the request.
If the error recurs, contact KVELL support and provide the request time, shop, and an example request body.