Payout via SBP from a Sber nominal account

This API method creates a payout to an individual by phone number via SBP from a Sber nominal account. The payout may complete immediately or remain in processing: determine the business result by the transaction status.

Integration flow

Make sure payouts via SBP from a Sber nominal account are enabled for the shop.
Get the recipient bank's bank_bic from the SBP list of banks and collect the recipient's details.
Generate a unique transaction, sign the exact request body, and send the payout.
If the response returns new or processing, poll the transaction status every 2 minutes or wait for the callback until the payout receives completed or canceled.

The callback is sent after the transaction moves to a final status, if a Finish callback URL is configured for the shop.

URL

ProductionStage

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

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

Request

Headers

Name	Type	Required	Description
`X-Api-Key`	string	Yes	Shop identifier.
`X-Signature`	string	Yes	Signature of the request body.

Building the signature

The request must be signed with an RSA/SHA-256 electronic signature. Pass the result in the X-Signature header.

The step-by-step algorithm, key requirements, examples for Python, PHP and OpenSSL, and troubleshooting for error 20002 are given in the general section «Building a signature for payouts».

Request body

Parameter	Type	Required	Description
`transaction`	string	Yes	Unique operation identifier in the merchant's system.
`amount`	integer	Yes	Amount in kopecks: from `0` to `100000000000`. For example, `100000` is 1000 ₽.
`description`	string	Yes	Description for the transaction, up to 140 characters. Do not use the characters `<`, `>`, `#`, `@`, `&`, `$`, `’`, `—`, or a non-breaking space.
`phone`	string	Yes	Recipient's phone number: 11 digits, without `+`, spaces, or separators. Example: `79991234567`.
`bank_bic`	string	Yes	BIC of the recipient's bank, 9 digits. Pass a value from the SBP list of banks.
`inn`	string	No	INN of the recipient individual, 12 digits.
`kvd`	string	No	Income type code: `1`, `2`, `3`, `4`, or `5`. The rules and values are given below.
`fio`	string	Conditional	Recipient's full name exactly as it appears in their identity document. Pass this if `fio_check` is `true`.
`fio_check`	boolean	No	`true` — verify the passed `fio` against the recipient's data from SBP. If `false` is passed or the field is omitted, the payout is made by `phone` and `bank_bic` without a full-name check.
`validate_self_employed`	boolean	No	`true` — verify the self-employed status before the payout. Defaults to `false`.
`customer`	string	No	Customer identifier, email, or phone number in the merchant's system.
`extra_data`	object	No	Additional merchant data.
`fiscal_data`	object	No	Data for receipt fiscalization under 54-FZ.

The kvd parameter

kvd is the income type code, field 20 of the payment order (229-FZ, Article 99, and parts 1 and 2 of Article 101). It is filled in when transferring wages, vacation pay, bonuses, payouts to self-employed individuals, and other payments to individuals.

You don't need to specify an income code if the money does not fall under income with collection restrictions under Article 99 or a collection ban under Article 101 of 229-FZ.

Value	Description
`1`	Collection amount is limited. Wages and other income for which Article 99 of 229-FZ sets limits on the amount withheld.
`2`	Periodic payments, collection is not possible. Periodic income that cannot be subject to collection under part 1 of Article 101 of 229-FZ, except for income under part 2 of Article 101.
`3`	Periodic payments, collection amount is not limited. Periodic income to which the collection restrictions under part 2 of Article 101 of 229-FZ do not apply.
`4`	One-time payments, collection is not possible. A one-time income that cannot be subject to collection under part 1 of Article 101 of 229-FZ, except for income under part 2 of Article 101.
`5`	One-time payments, collection amount is not limited. A one-time income to which the collection restrictions under part 2 of Article 101 of 229-FZ do not apply.

Full-name verification

If fio_check is true, Sber compares the passed full name against the recipient's data from SBP. If they don't match, the payout is not made. If the check is disabled, the money is transferred to the specified phone number and bank without a full-name check.

Example

JSON

{
  "transaction": "payout-nominal-sbp-20260911-0001",
  "amount": 100000,
  "description": "Выплата по договору 42",
  "phone": "79001234567",
  "bank_bic": "000000000",
  "inn": "000000000000",
  "kvd": "1",
  "fio": "Иванов Иван Иванович",
  "fio_check": true,
  "validate_self_employed": false,
  "customer": "customer@example.com"
}

Response

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

If no HTTP response is received

Treat a timeout or connection break the same as a 5XX response: the operation result is unknown, so first check the status by the original transaction. Do not create a new payout with a different identifier.

2004004034044225XX

Example 200 response (OK)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "processing",
  "transaction": "payout-nominal-sbp-20260911-0001",
  "amount": 100000,
  "commission": 0,
  "description": "Выплата по договору 42",
  "additional_data": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-09-11T10:30:00+00:00"
}

Response parameters

Parameter	Type	Description
`id`	string	Payout identifier in KVELL.
`status`	string	Current payout status. Possible values are listed in «Payout statuses».
`transaction`	string	Operation identifier passed by the merchant.
`amount`	integer	Payout amount in kopecks.
`commission`	integer	Commission in kopecks.
`description`	string \| null	Purpose of the payout.
`additional_data`	null	Additional data.
`error_code`	null	Rejection reason code. Possible values are listed in «Transaction error codes».
`error_message`	null	Description of the rejection reason. Returns `null` for a payout that was not rejected.
`created_at`	string	Date and time the payout was created, in ISO 8601 format.

Example 400 response (Bad Request)

{
  "errors": [
    {
      "code": 20039,
      "message": "Sber профиль не привязан к магазину"
    }
  ]
}

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. In the example — `20039`.
`errors[].message`	string	Description of why the request was rejected.

Example 403 response (Forbidden)

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

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. For access denial — `20037`.
`errors[].message`	string	Description of the reason access was denied.

Example 404 response (Not Found)

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

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. For a shop that was not found — `20006`.
`errors[].message`	string	Description of why the resource was not found.

What this response means

A shop with the passed X-Api-Key was not found in the selected environment. The payout was not created.

Example 422 response (Unprocessable Entity)

{
  "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 «HTTP response errors».
`errors[].code`	integer	Validation error code — `20098`.
`errors[].message`	string	Field name and the reason for the validation error.

Example 5XX response (Internal Server Error)

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

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. For an unknown error — `20000`.
`errors[].message`	string	Description of the technical error.

5XX, timeout, and connection break

In all of these cases, the request result is considered undefined: the payout may have been created even if the client did not receive a response. Keep the transaction in your system in the "processing" state until you get a confirmed result from KVELL.

This scenario can occur due to a network failure, a broken connection, a timeout, or a technical error on the server or client side.

Unified handling algorithm

Do not mark the payout as successful or rejected based solely on a technical error.
Save the payout in your system in the "processing" state.
Request the transaction status using the original transaction value.
If the transaction is found, keep checking it until you get a final status.
If status requests keep failing, contact support and provide the transaction.

Do not create a duplicate payout

Do not resend the payout with a new transaction until the result of the original operation has been established.

Payout statuses

Status	Final	What to do
`new`	No	The operation was created. Poll the transaction status.
`processing`	No	The payout is being processed. Poll the transaction status. Do not create a new payout.
`completed`	Yes	The payout was executed.
`canceled`	Yes	The payout was rejected.

The full reference of common operation statuses is given in «Transaction statuses».