Выплата СБП с конвертацией валюты

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

Когда использовать этот метод вместо базового

Используйте этот метод, если сумма выплаты изначально в валюте, отличной от валюты магазина (например, магазин рассчитывается в долларах, а выплаты уходят в рублях). Если currency не передан, метод ведёт себя идентично базовому методу выплаты СБП — конвертация не выполняется.

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

Получите bank_id банка-получателя из общего списка банков или из списка банков по номеру телефона.
При необходимости вызовите проверку возможности выплаты с конвертацией и дождитесь результата через метод получения статуса проверки.
Сформируйте уникальный transaction. Если сумма выплаты в валюте, отличной от валюты магазина, передайте её числовой код ISO 4217 в поле currency — сумма будет автоматически пересчитана перед выплатой. См. «Коды валют».
Подпишите точное тело запроса (включая поле currency, если оно передано) и отправьте выплату.
Проверяйте состояние операции по transaction, пока не получите completed или canceled.

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

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

URL

ProductionStage

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

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

Запрос

Заголовки

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

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

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

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

Тело запроса

Параметр	Тип	Обязательно	Описание
`phone`	string	Да	Номер телефона получателя: 11 цифр, без `+`, пробелов и разделителей. Пример: `79991234567`.
`fio`	string	Да	ФИО получателя. Для банков, не принимающих `Ё`/`ё`, используйте согласованный вариант с `Е`/`е`.
`bank_id`	string	Да	Идентификатор банка из списка банков или списка банков по телефону.
`amount`	integer	Да	Сумма в минорных единицах валюты, указанной в `currency` (копейки для рублей, центы для долларов и т.д.). Если `currency` не передан — сумма в копейках валюты payout-профиля магазина. Например, `15000` — 150.00 в соответствующей валюте.
`transaction`	string	Да	Уникальный идентификатор операции в системе мерчанта.
`description`	string	Да	Назначение выплаты, не более 110 символов.
`currency`	string	Нет	Числовой код исходной валюты ISO 4217 в виде строки, например `"840"` для USD. Если не передан, `amount` считается в валюте магазина — конвертация не выполняется. См. «Коды валют».
`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.

request_id из предварительной проверки без currency

Если вы вызывали проверку возможности выплаты с конвертацией и получили request_id, при создании самой выплаты amount всё равно нужно передать в исходной валюте вместе с полем currency — request_id не переносит результат конвертации автоматически.

Пример

JSON (с конвертацией)JSON (без конвертации)

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

{
  "phone": "79991234567",
  "fio": "Иванов Иван Иванович",
  "bank_id": "100000000008",
  "amount": 15000,
  "transaction": "payout-20260806-0002",
  "description": "Выплата по договору 42"
}

Ответ

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

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

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

2004004034044225XX

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

{
  "id": "3b3c19f4-c680-4f5d-bf2e-c0835439cf12",
  "status": "processing",
  "transaction": "payout-20260806-0001",
  "amount": 853846,
  "commission": 8538,
  "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	Сумма выплаты в минорных единицах валюты магазина. Если был передан `currency`, это результат конвертации, а не значение из запроса.
`commission`	integer	Комиссия в минорных единицах валюты магазина.
`description`	string \| null	Назначение выплаты.
`additional_data`	object \| null	Дополнительные данные операции, если они сформированы при обработке.
`error_code`	string \| null	Код причины отмены. Возможные значения приведены в разделе «Коды ошибок транзакции». Для незавершённой выплаты возвращается `null`.
`error_message`	string \| null	Описание причины отмены. Для незавершённой выплаты возвращается `null`.
`created_at`	string	Дата и время создания выплаты в формате ISO 8601.

Результат конвертации в ответе не возвращается

Ответ не содержит объект fx_conversion — используйте поле amount, чтобы узнать фактически выплаченную сумму в валюте payout-профиля. Если нужен курс и промежуточные значения конвертации именно перед выплатой, заранее вызовите «Проверку возможности выплаты с конвертацией» — она возвращает объект fx_conversion в ответе.

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

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

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

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

Лимит проверяется уже в валюте payout-профиля

Если передан currency, проверка лимита выплат по магазину выполняется после конвертации — по итоговой сумме в валюте payout-профиля, а не по значению amount из запроса.

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

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

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

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

Пример ответа 404 (Not Found): магазин не найден

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

Пример ответа 404 (Not Found): у payout-профиля не задана валюта

{
  "errors": [
    {
      "code": 20045,
      "message": "У payout-профиля магазина не задана валюта"
    }
  ]
}

Пример ответа 404 (Not Found): интеграция с Montra не настроена

{
  "errors": [
    {
      "code": 20044,
      "message": "Интеграция с Montra не настроена для магазина"
    }
  ]
}

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

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

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

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

20045 и 20044 возникают только если передан currency: сумма не может быть сконвертирована, выплата не создана. Для 20045 обратитесь в поддержку KVELL, чтобы указать валюту payout-профиля. Для 20044 обратитесь в поддержку KVELL, чтобы подключить интеграцию с провайдером курсов для магазина.

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

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

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

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

Формат поля currency

currency должен состоять из 1–3 цифр (^\d{1,3}$). Буквенные коды валют ("USD") отклоняются с ошибкой 20098.

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

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

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

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

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

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

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

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

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

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

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

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

Полный справочник статусов приведён в разделе «Статусы выплаты» базового метода — для выплат с конвертацией валюты они не отличаются.

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

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

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

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

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

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

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

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

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

Результат конвертации сохраняется до подтверждения

Если был передан currency, результат конвертации сохраняется вместе с сессией подтверждения и автоматически применяется при вызове метода подтверждения — повторно передавать currency не нужно.

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

Получить OTP-код у пользователя.
Передать transaction и OTP-код в метод подтверждения выплаты (метод общий для выплат с конвертацией валюты и без неё, отдельного v2-метода подтверждения нет).
После подтверждения получить финальный статус.