Payout to a bank account from a Sber nominal account

This API method creates a payout to an individual by bank details via a Sber nominal account. The payout may complete immediately or remain in processing — determine the result from the transaction status.

Integration flow

Generate a unique transaction and specify the recipient's details.
Sign the exact request body and send the payout.
Poll the operation status by transaction until you receive completed or canceled.

URL

ProductionStage

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

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

Request

Headers

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

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 transaction number on the merchant's side
`amount`	integer	Yes	Amount in kopecks
`description`	string	Yes	Transaction description
`fio`	string	Yes	Recipient's full name
`inn`	string	Yes	Individual's INN
`kvd`	string	Yes	Income type code (field 20 of the payment order, see 229-FZ)
`account`	object	Yes	Recipient's bank details (see below)
`snils`	string	No	Individual's SNILS
`validate_self_employed`	boolean	No	Check self-employed status before the payout (default `false`)
`customer`	string	No	Customer's email / phone number
`tax`	object	No	Tax details (see table below)
`extra_data`	json	No	Additional data
`fiscal_data`	json	No	Receipt fiscalization under 54-FZ

`account` object

Parameter	Type	Required	Description
`account_number`	string	Yes	Settlement account number
`bank_bic`	string	Yes	Recipient bank's BIC
`bank_cor_account`	string	Yes	Bank's correspondent account
`bank_name`	string	Yes	Bank name

`tax` object

Passed for a tax payment in favor of the FNS (Federal Tax Service).

Parameter	Type	Required	Description
`taxPayerInn`	string	Yes	Self-employed individual's (taxpayer's) INN, 12 digits
`tax_101`	string	Yes	Status of the settlement document preparer (field 101), 2 digits. Example: `01`
`tax_104`	string	Yes	Budget classification code KBK (field 104), 20 digits. Example: `18201061201010000510`
`tax_105`	string	Yes	OKTMO code (field 105), up to 8 digits. Example: `60701000`
`tax_106`	string	No	Basis of the tax payment (field 106), 2 uppercase letters or `0`. Example: `ТП`
`tax_107`	string	No	Tax period (field 107). Formats: `МС.03.2025`, `КВ.02.2025`, `ПЛ.02.2025`, `ГД.00.2025`
`tax_108`	string	No	Tax document number (field 108), up to 15 characters. Example: `ТР41797`
`tax_109`	string	No	Tax document date (field 109), format: `YYYY-MM-DD`. Example: `2025-04-15`
`tax_uin`	string	No	Unique tax payment identifier (UIN), 4–25 digits

The kvd parameter

kvd is the income type code, field 20 of the payment order (229-FZ, Art. 99 Parts 1, 2; Art. 101). It is filled in when transferring wages, vacation pay, bonuses, payouts to self-employed individuals, and other payouts to individuals. It is not filled in if the recipient is a sole proprietor or a legal entity.

Value	Description
`1`	Withholding amount is limited. Wages and other income for which Art. 99 of 229-FZ establishes withholding limits
`2`	Periodic payments, withholding not possible. Periodic income to which, under Art. 101 Part 1 of 229-FZ, withholding cannot be applied (except for income specified in Art. 101 Part 2 of 229-FZ)
`3`	Periodic payments, withholding amount not limited. Periodic income to which, under Art. 101 Part 2 of 229-FZ, withholding limits do not apply
`4`	One-time payments, withholding not possible. One-time income to which, under Art. 101 Part 1 of 229-FZ, withholding cannot be applied (except for income specified in Art. 101 Part 2 of 229-FZ)
`5`	One-time payments, withholding amount not limited. One-time income to which, under Art. 101 Part 2 of 229-FZ, withholding limits do not apply

Example

JSON

{
 "transaction": "sber-requisites-20260910-0001",
 "amount": 100000,
 "description": "Test payout under contract 42",
 "fio": "Testov Test Testovich",
 "inn": "000000000000",
 "kvd": "1",
 "account": {
   "account_number": "00000000000000000000",
   "bank_bic": "000000000",
   "bank_cor_account": "00000000000000000000",
   "bank_name": "Test Bank"
 },
 "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

Handle a timeout or connection break the same way as a 5XX response: the operation result is unknown, so first check the status using 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": "sber-requisites-20260910-0001",
  "amount": 100000,
  "commission": 0,
  "description": "Test payout under contract 42",
  "additional_data": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-09-10T10:30:00"
}

Response parameters

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

Example 400 response (Bad Request)

{
  "errors": [
    {
      "code": 20007,
      "message": "The transaction has already been made"
    }
  ]
}

Response parameters

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

Example 403 response (Forbidden)

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

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and recommendations are given in the «HTTP response errors» section.
`errors[].code`	integer	API error code.
`errors[].message`	string	Description of the error reason.

Example 404 response (Not Found)

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

Response parameters

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

What this response means

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

Example 422 response (Unprocessable Entity)

{
  "errors": [
    {
      "code": 20098,
      "message": "account.bank_bic: Field required"
    }
  ]
}

Response parameters

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

Example 5XX response (Internal Server Error)

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

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and recommendations are given in the «HTTP response errors» section.
`errors[].code`	integer	API error code.
`errors[].message`	string	Description of the error reason.

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 a "processing" state until you receive a confirmed result from KVELL.

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

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 a "processing" state.
Request the transaction status using the original transaction value.
If the transaction is found, keep checking it until you receive 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 completed.
`canceled`	Yes	The payout was rejected.

Payout to a bank account from a Sber nominal account

Integration flow

URL

Request

Headers

Building the signature

Request body

account object

tax object

Example

Response

Payout statuses

`account` object

`tax` object