Выплата по реквизитам через номинальный счёт Альфа-Банка

Создаёт выплату на банковский счёт по реквизитам получателя. Получателем может быть физическое лицо, индивидуальный предприниматель или юридическое лицо.

Сценарий интеграции

Соберите реквизиты получателя: наименование или ФИО, ИНН, номер счёта и БИК банка.
Сформируйте уникальный transaction, подпишите точное тело запроса и отправьте выплату.
Проверяйте состояние операции по transaction, пока не получите completed или canceled. Финальный статус также приходит на колбэк, если он настроен для магазина.

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

Запрос

Заголовки

Название	Тип	Обязательно	Описание
`X-Api-Key`	string	Да	Идентификатор магазина.
`X-Signature`	string	Да	Подпись тела запроса.

Формирование подписи

Запрос необходимо подписать электронной подписью RSA/SHA-256. Передайте результат в заголовке X-Signature.

Пошаговый алгоритм, требования к ключам, примеры для Python, PHP и OpenSSL, а также диагностика ошибки 20002 приведены в общем разделе «Формирование подписи для выплат».

Тело запроса

Параметр	Тип	Обязательно	Описание
`transaction`	string	Да	Уникальный идентификатор операции в системе мерчанта.
`amount`	integer	Да	Сумма в копейках. Например, `100000` — 1000 ₽.
`description`	string	Да	Назначение платежа. Передаётся в банк без изменений, до 210 символов.
`payee_name`	string	Да	Полное наименование получателя платежа: ФИО физического лица или название организации, до 160 символов.
`payee_inn`	string	Да	ИНН получателя платежа: 5, 10 или 12 цифр.
`payee_account`	string	Да	Номер счёта получателя платежа, 20 цифр.
`payee_bank_bic`	string	Да	БИК банка получателя платежа, 9 цифр.
`payee_bank_corr_account`	string \| null	Нет	Корреспондентский счёт банка получателя платежа, 20 цифр.
`payee_kpp`	string \| null	Нет	КПП получателя платежа, 9 символов либо `0`. Заполняется для юридического лица.
`income_type_code`	string \| null	Нет	Код вида дохода получателей выплаты по 229-ФЗ, одна цифра. Заполняется при выплате физическому лицу.
`vat`	object \| null	Нет	Данные НДС. Если объект не указан, то будут присвоены значения по умолчанию.
`departmental_info`	object \| null	Нет	Реквизиты налогового или иного бюджетного платежа.
`customer`	string \| null	Нет	Идентификатор плательщика, email или номер телефона.
`extra_data`	object \| null	Нет	Дополнительные данные мерчанта.
`fiscal_data`	object \| null	Нет	Данные для фискализации чека по 54-ФЗ.

Код вида дохода и сумма взыскания

При значениях income_type_code 1, 3 и 5 в description следует указать сумму взыскания в формате //ВЗС//сумма-копейки//, где сумма-копейки — это сумма взыскания. Пример при сумме взыскания в пять тысяч рублей: //ВЗС//5000-00//.

Объект `vat`

Параметр	Тип	Обязательно	Описание
`type`	string	Да	Способ расчёта НДС. Возможные значения приведены в таблице ниже.
`rate`	string \| null	Нет	Ставка НДС в процентах: `0`, `5`, `7`, `10` или `22`. По умолчанию `0`.

Значение `type`	Описание
`NO_VAT`	Не облагается НДС. В `description` необходимо указать «НДС не облагается». Значение по умолчанию.
`INCLUDED`	НДС включён в сумму платежа. В `description` необходимо указать посчитанный НДС, например «В том числе НДС 10%, 100.00 руб.».
`ONTOP`	НДС добавляется к сумме платежа. В `description` необходимо указать посчитанный НДС, например «Плюс 10% НДС, 100.00 руб.».
`MANUAL`	Ручной ввод НДС.
`AGENT`	НДС исчисляется налоговым агентом.

Объект `departmental_info`

Передаётся только при налоговом или ином бюджетном платеже. Номера в названиях полей соответствуют номерам реквизитов платёжного поручения.

Параметр	Тип	Обязательно	Описание
`drawer_status_101`	string \| null	Нет	Статус составителя расчётного документа. Например, `01`.
`kbk`	string \| null	Нет	Код бюджетной классификации. Например, `18210102010011000110`.
`oktmo`	string \| null	Нет	Код ОКТМО. Например, `45902000`.
`reason_code_106`	string \| null	Нет	Основание налогового платежа. Например, `ТП`.
`tax_period_107`	string \| null	Нет	Налоговый период. Форматы: `МС.03.2026`, `КВ.02.2026`, `ПЛ.02.2026`, `ГД.00.2026`.
`doc_number_108`	string \| null	Нет	Номер налогового документа.
`doc_date_109`	string \| null	Нет	Дата налогового документа в формате `YYYY-MM-DD`.
`payment_kind_110`	string \| null	Нет	Код выплат.
`uip`	string \| null	Нет	Уникальный идентификатор платежа (УИП).

Пример

Реквизиты получателя в примерах взяты из тестовых данных Альфа-Банка. Набор значений и ожидаемые статусы приведены в разделе «Тестирование».

Юридическое лицоФизическое лицо

{
  "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"
}

Ответ

Выберите HTTP-код, чтобы посмотреть пример, параметры ответа и рекомендуемые действия.

Если HTTP-ответ не получен

Таймаут или разрыв соединения обрабатывайте так же, как ответ 5XX: результат операции неизвестен, поэтому сначала проверьте статус по исходному transaction. Не создавайте новую выплату с другим идентификатором.

2004004034044225XX

Пример ответа 200 (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"
}

Параметры ответа

Параметр	Тип	Описание
`id`	string	Идентификатор выплаты в KVELL.
`status`	string	Текущий статус выплаты. Возможные значения приведены в разделе «Статусы выплаты».
`transaction`	string	Идентификатор операции, переданный мерчантом.
`amount`	integer	Сумма выплаты в копейках.
`commission`	integer	Комиссия в копейках.
`description`	string \| null	Назначение платежа. Может включать префикс, настроенный для магазина.
`additional_data`	object \| null	Дополнительные данные, полученные при обработке выплаты.
`error_code`	string \| null	Код причины отклонения. Возможные значения приведены в разделе «Коды ошибок транзакции».
`error_message`	string \| null	Описание причины отклонения. Для неотклонённой выплаты возвращается `null`.
`created_at`	string	Дата и время создания выплаты в формате ISO 8601.

Что означает ответ

Выплата создана, платёжное поручение передано в Альфа-Банк. Банк исполняет поручение асинхронно, поэтому финальный бизнес-результат определяет только статус выплаты.

Что делать дальше

Сохраните и оставьте выплату у себя в состоянии «обрабатывается».
Проверяйте статус транзакции по transaction, пока не получите completed или canceled.

Пример ответа 400 (Bad Request)

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

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки. В примере — `20007`.
∟ `message`	string	Описание причины отклонения запроса.

Пример ответа 403 (Forbidden)

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

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки. Для запрета доступа — `20037`.
∟ `message`	string	Описание причины запрета доступа.

Пример ответа 404 (Not Found)

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

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки. Для ненайденного магазина — `20006`.
∟ `message`	string	Описание причины, по которой ресурс не найден.

Что означает ответ

Магазин с переданным X-Api-Key не найден в выбранном контуре. Выплата не создана.

Пример ответа 422 (Unprocessable Entity)

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

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок валидации. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки.
∟ `message`	string	Причина ошибки валидации.

Пример ответа 5XX (Internal Server Error)

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

Параметры ответа

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
∟ `code`	integer	Код ошибки. Для неизвестной ошибки — `20000`.
∟ `message`	string	Описание технической ошибки.

5XX, таймаут и разрыв соединения

Во всех этих случаях результат запроса считается неопределённым: выплата могла быть создана, даже если клиент не получил ответ. Оставьте транзакцию в своей системе в состоянии «обрабатывается» до получения подтверждённого результата от KVELL.

Такой сценарий может возникнуть из-за сетевого сбоя, разрыва соединения, превышения времени ожидания, технической ошибки сервера или клиентского ПО.

Единый алгоритм обработки

Не помечайте выплату успешной или отклонённой только на основании технической ошибки.
Сохраните выплату у себя в состоянии «обрабатывается».
Запросите статус транзакции по исходному значению transaction.
Если транзакция найдена, проверяйте её до получения финального статуса.
Если запросы статуса продолжают завершаться ошибкой, обратитесь в поддержку и передайте transaction.

Не создавайте дублирующую выплату

Не отправляйте выплату повторно с новым transaction, пока результат исходной операции не установлен.

Статусы выплаты

Статус	Финальный	Что делать
`new`	Нет	Запрашивать статус транзакции.
`processing`	Нет	Запрашивать статус транзакции. Не создавать новую выплату.
`completed`	Да	Выплата исполнена банком.
`canceled`	Да	Выплата отклонена. Причина — в `error_code` и `error_message`.

Почему статус processing держится дольше обычного

Альфа-Банк может отклонить зачисление уже после исполнения платёжного поручения, если банк получателя вернёт платёж. Поэтому KVELL подтверждает статус completed не сразу после исполнения, а после контрольного периода. Ориентируйтесь только на финальные статусы.

Полный справочник общих статусов операций приведён в разделе «Статусы транзакции».

Выплата по реквизитам через номинальный счёт Альфа-Банка

Сценарий интеграции

URL

Запрос

Заголовки

Формирование подписи

Тело запроса

Объект vat

Объект departmental_info

Пример

Ответ

Статусы выплаты

Объект `vat`

Объект `departmental_info`