Совершение выплаты через СБП

Создаёт выплату физическому лицу по номеру телефона и выбранному банку-получателю.

Выплата в другой валюте

Если сумма выплаты изначально в валюте, отличной от валюты магазина, используйте «Выплата СБП с конвертацией» — тот же метод с дополнительным полем currency, конвертирующим сумму перед выплатой.

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

Получите bank_id банка-получателя из общего списка банков или из списка банков по номеру телефона.
При необходимости вызовите проверку возможности выплаты и дождитесь результата через метод получения статуса проверки.
Сформируйте уникальный transaction, подпишите точное тело запроса и отправьте выплату.
Проверяйте состояние операции по transaction, пока не получите completed или canceled.

Когда нужна предварительная проверка

Проверка позволяет заранее убедиться, что банк может принять выплату, и получить nspk_id и request_id. Для выплат через Альфа-Банк передайте полученный nspk_id, если перед созданием выплаты выполнялась проверка.

URL

ProductionStage

POST https://api.pay.kvell.group/v1/orders/payout/sbp

POST https://api.pay.stage.kvell.group/v1/orders/payout/sbp

Запрос

Заголовки

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

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

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

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

Тело запроса

Параметр	Тип	Обязательно	Описание
`phone`	string	Да	Номер телефона получателя: 11 цифр, без `+`, пробелов и разделителей. Пример: `79991234567`.
`fio`	string	Да	ФИО получателя. Для банков, не принимающих `Ё`/`ё`, используйте согласованный вариант с `Е`/`е`.
`bank_id`	string	Да	Идентификатор банка из списка банков или списка банков по телефону.
`amount`	integer	Да	Сумма в копейках. Например, `15000` — 150 ₽.
`transaction`	string	Да	Уникальный идентификатор операции в системе мерчанта.
`description`	string	Да	Назначение выплаты, не более 110 символов.
`fio_check`	boolean	Нет	`true` — проверить совпадение переданного ФИО с ФИО, полученным от НСПК.
`bank_bic`	string	Условно	БИК из ответа метода получения банков. Требование зависит от настроенного банка-эквайера.
`nspk_id`	string	Условно	Платёжная ссылка, полученная на этапе вызова метода статуса возможности выплаты. При отсутствии в запросе ссылка будет получена отдельным запросом в НСПК в рамках выполнения платежа. Обязательно для работы через Альфа-Банк, если предварительно вызывались методы проверки возможности выплаты.
`request_id`	string	Условно	Идентификатор запроса проверки возможности выплаты. Требование зависит от настроенного банка-эквайера.
`customer`	string	Нет	Email или телефон клиента в системе мерчанта.
`extra_data`	object	Нет	Дополнительные данные мерчанта.
`fiscal_data`	object	Нет	Данные для фискализации чека по 54-ФЗ.

Условные параметры

Необходимость request_id и bank_bic зависит от банка-эквайера, через который настроены выплаты магазина. Если схема интеграции неизвестна, уточните её у менеджера KVELL до запуска в Production.

Пример

JSON

{
  "phone": "79991234567",
  "fio": "Иванов Иван Иванович",
  "bank_id": "100000000008",
  "amount": 15000,
  "transaction": "payout-20260806-0001",
  "description": "Выплата по договору 42",
  "nspk_id": "<nspk-id>",
  "request_id": "<request-id>"
}

Ответ

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

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

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

2004004034044225XX

Пример ответа 200 (OK)

{
  "id": "3b3c19f4-c680-4f5d-bf2e-c0835439cf12",
  "status": "processing",
  "transaction": "payout-20260806-0001",
  "amount": 15000,
  "commission": 150,
  "description": "Выплата по договору 42",
  "additional_data": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-08-06T09: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	Код причины отмены. Возможные значения приведены в разделе «Коды ошибок транзакции». Для незавершённой выплаты возвращается `null`.
`error_message`	string \| null	Описание причины отмены. Для незавершённой выплаты возвращается `null`.
`created_at`	string	Дата и время создания выплаты в формате ISO 8601.

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

{
  "errors": [
    {
      "code": 20019,
      "message": "Превышен лимит выплат по магазину"
    }
  ]
}

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

Параметр	Тип	Описание
`errors`	array	Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
`errors[].code`	integer	Код ошибки. В примере — `20019`.
`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`	Да	Выплата отклонена.

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

Подтверждение через OTP

Используется только для магазинов с включённым OTP

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

При включённом OTP вместо объекта созданной выплаты API вернёт:

{
  "status": "wait_confirm",
  "transaction": "payout-20260806-0001"
}

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

Параметр	Тип	Описание
`status`	string	Статус `wait_confirm`: выплата ожидает подтверждения OTP-кодом.
`transaction`	string	Идентификатор операции, который необходимо передать в метод подтверждения.

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

Запрос принят, но выплата ожидает подтверждения и ещё не перешла к обработке банком. Поэтому в ответе нет id, amount, commission и created_at.

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

Получить OTP-код у пользователя.
Передать transaction и OTP-код в метод подтверждения выплаты.
После подтверждения получить финальный статус.