Payout to a bank account

Creates a payout to a bank account by the recipient's bank details. The recipient can be an individual, a sole proprietor, or a legal entity.

Integration scenario

Collect the recipient's details: full name or company name, INN, account number, and bank BIC.
Generate a unique transaction, sign the exact request body, and send the payout.
Check the operation status by transaction until you receive completed or canceled. The final status is also delivered via callback, if configured for the shop.

URL

ProductionStage

POST https://api.pay.kvell.group/v2/orders/payout/requisites

POST https://api.pay.stage.kvell.group/v2/orders/payout/requisites

Request

Headers

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

Generating 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, as well as diagnostics for error 20002, are provided in the general section «Generating 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. For example, `100000` is 1000 ₽.
`currency`	string	No	Numeric ISO 4217 code of the source currency as a string, for example `"840"` for USD. If not passed, `amount` is treated as being in the shop's currency — no conversion is performed. See «Currency codes».
`description`	string	Yes	Payment purpose. Passed to the bank unchanged, up to 210 characters.
`payee_name`	string	Yes	Full name of the payment recipient: an individual's full name or an organization's name, up to 160 characters.
`payee_inn`	string	Yes	Payment recipient's INN: 5, 10, or 12 digits.
`payee_account`	string	Yes	Payment recipient's account number, 20 digits.
`payee_bank_bic`	string	Yes	BIC of the payment recipient's bank, 9 digits.
`payee_bank_corr_account`	string \| null	No	Correspondent account of the payment recipient's bank, 20 digits.
`payee_kpp`	string \| null	No	KPP of the payment recipient, 9 characters or `0`. Filled in for a legal entity.
`income_type_code`	string \| null	No	Income type code of the payout recipient under Federal Law 229-FZ, a single digit. Filled in for a payout to an individual.
`vat`	object \| null	No	VAT data. If the object is not specified, default values are assigned.
`departmental_info`	object \| null	No	Requisites of a tax or other budget payment.
`customer`	string \| null	No	Payer identifier, email, or phone number.
`extra_data`	object \| null	No	Additional merchant data.
`fiscal_data`	object \| null	No	Data for receipt fiscalization under 54-FZ.

Income type code and garnishment amount

For income_type_code values 1, 3, and 5, description must include the garnishment amount in the format //ВЗС//rubles-kopecks//. Example for a garnishment amount of five thousand rubles: //ВЗС//5000-00// (RUB 5,000.00).

The `vat` object

Parameter	Type	Required	Description
`type`	string	Yes	VAT calculation method. Possible values are listed in the table below.
`rate`	string \| null	No	VAT rate in percent: `0`, `5`, `7`, `10`, or `22`. Defaults to `0`.

`type` value	Description
`NO_VAT`	Not subject to VAT. `description` must state "НДС не облагается" ("VAT not applicable"). Default value.
`INCLUDED`	VAT is included in the payment amount. `description` must state the calculated VAT, for example "В том числе НДС 10%, 100.00 руб." ("Including 10% VAT, 100.00 rub.").
`ONTOP`	VAT is added to the payment amount. `description` must state the calculated VAT, for example "Плюс 10% НДС, 100.00 руб." ("Plus 10% VAT, 100.00 rub.").
`MANUAL`	Manually entered VAT.
`AGENT`	VAT calculated by a tax agent.

The `departmental_info` object

Passed only for a tax or other budget payment. The numbers in the field names correspond to the numbers of the payment order details.

Parameter	Type	Required	Description
`drawer_status_101`	string \| null	No	Status of the settlement document drafter. For example, `01`.
`kbk`	string \| null	No	Budget classification code. For example, `18210102010011000110`.
`oktmo`	string \| null	No	OKTMO code. For example, `45902000`.
`reason_code_106`	string \| null	No	Basis for the tax payment. For example, `ТП`.
`tax_period_107`	string \| null	No	Tax period. Formats: `МС.03.2026`, `КВ.02.2026`, `ПЛ.02.2026`, `ГД.00.2026`.
`doc_number_108`	string \| null	No	Tax document number.
`doc_date_109`	string \| null	No	Tax document date in `YYYY-MM-DD` format.
`payment_kind_110`	string \| null	No	Payout code.
`uip`	string \| null	No	Unique payment identifier (UIP).

Example

The recipient details in the examples are taken from test data. The set of values and expected statuses are given in the «Testing» section.

Legal entityIndividual

{
  "transaction": "payout-req-20260827-0001",
  "amount": 100000,
  "currency": "840",
  "description": "Оплата заказа №1. НДС не облагается",
  "payee_name": "Общество с ограниченной ответственностью \"Центр \"ИННОВАЦИЯ\"",
  "payee_inn": "7723870785",
  "payee_kpp": "553453453",
  "payee_account": "40702810564564564531",
  "payee_bank_bic": "040173745",
  "payee_bank_corr_account": "30101810800000000745",
  "vat": {
    "type": "NO_VAT",
    "rate": "0"
  }
}

{
  "transaction": "payout-req-20260827-0002",
  "amount": 100000,
  "currency": "840",
  "description": "Выплата по договору 42. //ВЗС//1000-00//",
  "payee_name": "Иванов Иван Иванович",
  "payee_inn": "771234567890",
  "payee_account": "40817810099910004312",
  "payee_bank_bic": "040173745",
  "payee_bank_corr_account": "30101810800000000745",
  "income_type_code": "1",
  "customer": "customer@example.com"
}

Response

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

If no HTTP response is received

Treat a timeout or a broken connection the same way 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 (OK) response

{
  "id": "3b3c19f4-c680-4f5d-bf2e-c0835439cf12",
  "status": "processing",
  "transaction": "payout-req-20260827-0001",
  "amount": 100000,
  "currency": "840",
  "commission": 1500,
  "description": "Оплата заказа №1. НДС не облагается",
  "additional_data": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-08-27T09:15:27.231000+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	Payment purpose. May include a prefix configured for the shop.
`additional_data`	object \| null	Additional data received while processing the payout.
`error_code`	string \| null	Rejection reason code. Possible values are listed in «Transaction error codes».
`error_message`	string \| 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.

What this response means

The payout has been created and the payment order has been sent to the bank. The bank executes the order asynchronously, so only the payout status determines the final business outcome.

What to do next

Save the payout and keep it in "processing" state on your side.
Check the transaction status by transaction until you receive completed or canceled.

Example 400 (Bad Request) response

{
  "errors": [
    {
      "code": 20007,
      "message": "Транзакция совершалась прежде"
    }
  ]
}

Response parameters

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

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 «HTTP response errors».
∟ `code`	integer	Error code. For access denial — `20037`.
∟ `message`	string	Description of the reason access was denied.

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 «HTTP response errors».
∟ `code`	integer	Error code. For a shop not found — `20006`.
∟ `message`	string	Description of why the resource was not found.

What this response means

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

Example 422 (Unprocessable Entity) response

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

Response parameters

Parameter	Type	Description
`errors`	array	List of validation errors. Codes and handling recommendations are given in «HTTP response errors».
∟ `code`	integer	Error code.
∟ `message`	string	Reason for the validation error.

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 «HTTP response errors».
∟ `code`	integer	Error code. For an unknown error — `20000`.
∟ `message`	string	Description of the technical error.

5XX, timeout, and broken connection

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 "processing" state in your system until you receive 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 "processing" state on your side.
Request the transaction status by 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 is established.

Payout statuses

Status	Final	What to do
`new`	No	Request the transaction status.
`processing`	No	Request the transaction status. Do not create a new payout.
`completed`	Yes	The payout has been executed by the bank.
`canceled`	Yes	The payout was rejected. The reason is in `error_code` and `error_message`.

Why the processing status lasts longer than usual

The bank may reject the credit even after executing the payment order, if the recipient's bank returns the payment. That's why KVELL confirms the completed status not immediately after execution, but after a control period. Rely only on final statuses.

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

Payout to a bank account

Integration scenario

URL

Request

Headers

Generating the signature

Request body

The vat object

The departmental_info object

Example

Response

Payout statuses

The `vat` object

The `departmental_info` object