Выплата через СБП с номинального счёта Сбера

API-метод создаёт выплату физическому лицу по номеру телефона через СБП с номинального счёта Сбера. Выплата может завершиться сразу или остаться в обработке: бизнес-результат определяйте по статусу транзакции.

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

Убедитесь, что для магазина подключены выплаты через СБП с номинального счёта Сбера.
Получите bank_bic банка-получателя из списка банков СБП и соберите данные получателя.
Сформируйте уникальный transaction, подпишите точное тело запроса и отправьте выплату.
Если в ответе получен new или processing, проверяйте статус транзакции с интервалом 2 минуты или дождитесь колбэка, пока выплата не получит completed или canceled.

Колбэк отправляется после перехода транзакции в финальный статус, если для магазина настроен Finish callback URL.

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

Запрос

Заголовки

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

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

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

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

Тело запроса

Параметр	Тип	Обязательно	Описание
`transaction`	string	Да	Уникальный идентификатор операции в системе мерчанта.
`amount`	integer	Да	Сумма в копейках: от `0` до `100000000000`. Например, `100000` — 1000 ₽.
`description`	string	Да	Описание к транзакции, не более 140 символов. Не используйте символы `<`, `>`, `#`, `@`, `&`, `$`, `’`, `—` и неразрывный пробел.
`phone`	string	Да	Номер телефона получателя: 11 цифр, без `+`, пробелов и разделителей. Пример: `79991234567`.
`bank_bic`	string	Да	БИК банка-получателя, 9 цифр. Передайте значение из списка банков СБП.
`inn`	string	Нет	ИНН получателя — физического лица, 12 цифр.
`kvd`	string	Нет	Код вида дохода: `1`, `2`, `3`, `4` или `5`. Правила заполнения и значения приведены ниже.
`fio`	string	Условно	ФИО получателя в том виде, в котором оно указано в документе, удостоверяющем личность. Передайте, если `fio_check` равно `true`.
`fio_check`	boolean	Нет	`true` — проверить переданное `fio` по данным получателя из СБП. Если передать `false` или не указывать поле, выплата выполняется по `phone` и `bank_bic` без проверки ФИО.
`validate_self_employed`	boolean	Нет	`true` — проверить статус самозанятого перед выплатой. По умолчанию — `false`.
`customer`	string	Нет	Идентификатор клиента, email или номер телефона в системе мерчанта.
`extra_data`	object	Нет	Дополнительные данные мерчанта.
`fiscal_data`	object	Нет	Данные для фискализации чека по 54-ФЗ.

Параметр kvd

kvd — код вида дохода, поле 20 в платёжном поручении (229-ФЗ, статья 99, части 1 и 2 статьи 101). Заполняется при перечислении заработной платы, отпускных, премий, выплатах самозанятым и иных выплатах физическим лицам.

Код дохода указывать не нужно, если деньги не относятся к доходам с ограничениями взыскания по статье 99 или запретом взыскания по статье 101 229-ФЗ.

Значение	Описание
`1`	Размер взыскания ограничен. Заработная плата и иные доходы, в отношении которых статья 99 229-ФЗ устанавливает ограничения размера удержания.
`2`	Периодические выплаты, взыскание невозможно. Периодические доходы, на которые по части 1 статьи 101 229-ФЗ нельзя обратить взыскание, кроме доходов из части 2 статьи 101.
`3`	Периодические выплаты, размер взыскания не ограничен. Периодические доходы, к которым по части 2 статьи 101 229-ФЗ ограничения взыскания не применяются.
`4`	Разовые выплаты, взыскание невозможно. Единовременный доход, на который по части 1 статьи 101 229-ФЗ нельзя обратить взыскание, кроме доходов из части 2 статьи 101.
`5`	Разовые выплаты, размер взыскания не ограничен. Единовременный доход, к которому по части 2 статьи 101 229-ФЗ ограничения взыскания не применяются.

Проверка ФИО

Если fio_check равно true, Сбер сравнивает переданное ФИО с данными получателя из СБП. При расхождении выплата не выполняется. Если проверка отключена, деньги переводятся по указанным номеру телефона и банку без проверки ФИО.

Пример

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

Ответ

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

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

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

2004004034044225XX

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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