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

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

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

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

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

Получите bank_id из списка банков СБП.
Сформируйте запрос с номером телефона, банком получателя и суммой выплаты. Если сумма в валюте, отличной от валюты магазина, передайте её числовой код ISO 4217 в поле currency. См. «Коды валют».
Сохраните request_id из ответа 200. Этот ответ означает только, что запрос на проверку зарегистрирован.
Запрашивайте статус проверки с тем же request_id, пока не получите success или error. При processing продолжайте опрос, не создавая новую проверку.
При создании самой выплаты через метод выплаты с конвертацией передайте исходную сумму и currency заново — конвертация на этом шаге выполняется повторно.

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

Проверка нужна, если до создания выплаты требуется убедиться, что выбранный банк может принять перевод на указанный номер телефона, получить ФИО от НСПК, проверить его совпадение или заранее увидеть сумму и курс конвертации.

URL

ProductionStage

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

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

Запрос

Заголовки

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

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

Объедините X-Api-Key, phone, bank_id и secret_key без разделителей, вычислите SHA-256 от полученной строки в кодировке UTF-8 и передайте хеш в нижнем регистре в заголовке X-Signature.

SHA256(X-Api-Key + phone + bank_id + secret_key)

secret_key находится в настройках магазина. Порядок значений изменять нельзя. Поле currency в подпись не входит.

Тело запроса

Параметр	Тип	Обязательно	Описание
`amount`	integer	Да	Сумма предполагаемой выплаты в минорных единицах валюты, указанной в `currency`. Если `currency` не передан — сумма в копейках валюты payout-профиля магазина. Например, `10000` — 100.00 в соответствующей валюте.
`bank_id`	string	Да	Идентификатор банка получателя из списка банков СБП.
`bank_bic`	string	Условно	БИК из списка банков. Обязателен, если его требует банк-эквайер. Уточняйте у менеджера.
`phone`	string	Да	Номер телефона получателя: 11 цифр, без `+`, пробелов, скобок и разделителей. Пример: `79999999999`.
`currency`	string	Нет	Числовой код исходной валюты ISO 4217 в виде строки, например `"840"` для USD. Если не передан, `amount` считается уже в валюте магазина — конвертация не выполняется. См. «Коды валют».
`fio`	string	Нет	ФИО получателя. Используется вместе с `fio_check` для проверки совпадения с данными НСПК.
`fio_check`	boolean	Нет	`true` — проверить совпадение `fio` с ФИО, полученным от НСПК.
`description`	string	Нет	Назначение предполагаемой выплаты. По умолчанию — `выплата`. Итоговая строка вместе с префиксом магазина — не более 110 символов.

Проверка ФИО

fio и fio_check можно не передавать, в таком случае при получении статуса возможности выплаты будет приходить ФИО клиента.

Если передаёте fio_check: true, используйте ФИО в том же виде, в котором оно зарегистрировано в банке получателя. Некоторые банковские каналы отклоняют символы Ё/ё ещё до проверки совпадения. Если получили ошибку формата, передайте вариант с Е/е.

Пример

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

{
  "amount": 10000,
  "currency": "840",
  "bank_id": "100100000014",
  "fio": "Иванов Иван Иванович",
  "fio_check": true,
  "phone": "79999999999",
  "description": "Выплата по договору 42"
}

curl --request POST \
  --url 'https://api.pay.stage.kvell.group/v2/orders/payout/sbp/check' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000' \
  --header 'X-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef' \
  --data '{"amount":10000,"currency":"840","bank_id":"100100000014","fio":"Иванов Иван Иванович","fio_check":true,"phone":"79999999999","description":"Выплата по договору 42"}'

Ответ

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

2004004034044225XX

Пример ответа 200 (OK): с конвертацией

{
  "request_id": "check-req-20260811-0001",
  "fx_conversion": {
    "source_currency": "840",
    "source_amount": 10000,
    "target_currency": "643",
    "target_amount": 853846,
    "rate_source": "montra",
    "source_to_base": 12210,
    "base_to_target": 143,
    "base_currency": "UZS",
    "converted_at": "2026-08-11T09:15:20.000000+00:00"
  }
}

Пример ответа 200 (OK): без конвертации

{
  "request_id": "check-req-20260811-0002",
  "fx_conversion": null
}

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

Параметр	Тип	Описание
`request_id`	string	Идентификатор зарегистрированной проверки. Используется для получения её статуса.
`fx_conversion`	object \| null	Результат конвертации суммы. `null`, если `currency` не был передан в запросе.
`fx_conversion.source_currency`	string	Числовой код исходной валюты — значение `currency` из запроса.
`fx_conversion.source_amount`	integer	Сумма из запроса, в минорных единицах исходной валюты.
`fx_conversion.target_currency`	string	Числовой код валюты payout-профиля магазина.
`fx_conversion.target_amount`	integer	Сконвертированная сумма в минорных единицах валюты магазина — именно эта сумма будет использована при создании выплаты.
`fx_conversion.rate_source`	string	Источник курса: `montra` — курс банка-партнёра; `same_currency` — конвертация не потребовалась, `currency` совпал с валютой профиля.
`fx_conversion.source_to_base`	number \| null	Курс исходной валюты к базовой (`UZS`). Присутствует только при `rate_source: "montra"`.
`fx_conversion.base_to_target`	number \| null	Курс базовой валюты (`UZS`) к валюте магазина. Присутствует только при `rate_source: "montra"`.
`fx_conversion.base_currency`	string \| null	Базовая валюта расчёта курса. Присутствует только при `rate_source: "montra"`, значение — всегда `"UZS"`.
`fx_conversion.converted_at`	string	Дата и время расчёта конвертации в формате ISO 8601.

Курс актуален только на момент ответа

fx_conversion рассчитывается непосредственно в момент вызова этого метода и не сохраняется на стороне KVELL. Курс на момент фактического создания выплаты может отличаться — сохраняйте fx_conversion у себя только для отображения пользователю, а не как гарантию итоговой суммы.

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

Сохраните request_id.
При необходимости покажите пользователю сумму и курс из fx_conversion.
Вызовите метод получения статуса проверки.

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

{
  "errors": [
    {
      "code": 20002,
      "message": "Неверная подпись"
    }
  ]
}

Пример ошибки банка

{
  "errors": [
    {
      "code": 20099,
      "message": "1706: Банк с RbankID = 100000000118 не найден!"
    }
  ]
}

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

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

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

При 20002 проверьте порядок значений в подписи и секретный ключ магазина.
При 20099 исправьте причину из message.
Если изменились phone или bank_id, пересчитайте X-Signature, затем повторите запрос.

Пример ответа 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	Описание ресурса, который не найден.

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

20045 и 20044 возникают только если передан currency: сумма не может быть сконвертирована, проверка не зарегистрирована, request_id не создан.

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

При 20006 проверьте X-Api-Key и контур запроса.
При 20045/20044 обратитесь в поддержку KVELL, чтобы настроить валюту payout-профиля или интеграцию с провайдером курсов, либо отправьте запрос без currency.
Повторите запрос только после исправления причины ошибки.

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

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

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

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

Формат поля currency

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

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

При 20098 исправьте поля, указанные в errors[].message.
При 20099 проверьте параметры запроса; если причина непонятна, обратитесь в поддержку KVELL.
Если изменились phone или bank_id, пересчитайте X-Signature.
Отправьте исправленный запрос и сохраните request_id из ответа 200.

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

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

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

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

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

Техническая ошибка не означает, что проверка реквизитов или конвертация завершились с бизнес-статусом error. Запрос мог быть зарегистрирован, даже если клиент не получил request_id. Выплата или финансовая транзакция этим методом не создаётся.

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

Если request_id был получен ранее, запросите статус с тем же идентификатором.
Если request_id не получен, попробуйте повторить запрос.
При повторяющейся ошибке обратитесь в поддержку KVELL и передайте время запроса, магазин и пример тела запроса.