Payout to a bank account via an Alfa-Bank nominal 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 flow

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

URL

ProductionStage

POST https://api.pay.kvell.group/v1/orders/payout/nominal-accounts/requisites/alfa

POST https://api.pay.stage.kvell.group/v1/orders/payout/nominal-accounts/requisites/alfa

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. For example, `100000` is 1000 ₽.
`description`	string	Yes	Purpose of the payment. Passed to the bank unchanged, up to 210 characters.
`payee_name`	string	Yes	Full name of the payment recipient: the individual's full name or organization name, up to 160 characters.
`payee_inn`	string	Yes	Recipient's INN: 5, 10, or 12 digits.
`payee_account`	string	Yes	Recipient's account number, 20 digits.
`payee_bank_bic`	string	Yes	BIC of the recipient's bank, 9 digits.
`payee_bank_corr_account`	string \| null	No	Correspondent account of the recipient's bank, 20 digits.
`payee_kpp`	string \| null	No	Recipient's KPP, 9 characters or `0`. Filled in for a legal entity.
`income_type_code`	string \| null	No	Income type code for the payout under Federal Law 229-FZ, one 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 for 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 the enforcement amount

For income_type_code values 1, 3, and 5, indicate the enforcement (collection) amount in description using the format //ВЗС//rubles-kopecks//. Example for a collection 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 as a percentage: `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, e.g. "В том числе НДС 10%, 100.00 руб." ("Including 10% VAT, 100.00 RUB").
`ONTOP`	VAT is added on top of the payment amount. `description` must state the calculated VAT, e.g. "Плюс 10% НДС, 100.00 руб." ("Plus 10% VAT, 100.00 RUB").
`MANUAL`	Manual VAT entry.
`AGENT`	VAT is 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 drawer of the settlement document. 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	Payment type code.
`uip`	string \| null	No	Unique payment identifier (UIP).

Example

Recipient details in the examples are taken from Alfa-Bank's test data. The set of values and expected statuses are given in the «Testing» section.

Legal entityIndividual

{
  "transaction": "payout-req-20260827-0001",
  "amount": 100000,
  "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,
  "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 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": "3b3c19f4-c680-4f5d-bf2e-c0835439cf12",
  "status": "processing",
  "transaction": "payout-req-20260827-0001",
  "amount": 100000,
  "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	Purpose of the payment. 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 was created, and the payment order was sent to Alfa-Bank. The bank processes the order asynchronously, so only the payout status determines the final business result.

What to do next

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

Example 400 response (Bad Request)

{
  "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 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».
∟ `code`	integer	Error code. For access denial — `20037`.
∟ `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».
∟ `code`	integer	Error code. For a shop that was not found — `20006`.
∟ `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": "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 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».
∟ `code`	integer	Error code. For an unknown error — `20000`.
∟ `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	Poll the transaction status.
`processing`	No	Poll the transaction status. Do not create a new payout.
`completed`	Yes	The payout was executed by the bank.
`canceled`	Yes	The payout was rejected. The reason is in `error_code` and `error_message`.

Why the processing status can take longer than usual

Alfa-Bank can reject the credit even after the payment order has been executed, 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.

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

Payout to a bank account via an Alfa-Bank nominal account

Integration flow

URL

Request

Headers

Building the signature

Request body

The vat object

The departmental_info object

Example

Response

Payout statuses

The `vat` object

The `departmental_info` object