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

Метод проверки реквизитов получателя перед выплатой через СБП.

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

Получите bank_id из списка банков СБП.
Сформируйте запрос с номером телефона, банком получателя и суммой выплаты.
Сохраните request_id из ответа 200. Этот ответ означает только, что запрос на проверку зарегистрирован.
Запрашивайте статус проверки с тем же request_id, пока не получите success или error. При processing продолжайте опрос, не создавая новую проверку.

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

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

URL

ProductionStage

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

POST https://api.pay.stage.kvell.group/v1/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 находится в настройках магазина. Порядок значений изменять нельзя.

Тело запроса

Параметр	Тип	Обязательно	Описание
`amount`	integer	Да	Сумма предполагаемой выплаты в копейках. Например, `15000` — 150 ₽.
`bank_id`	string	Да	Идентификатор банка получателя из списка банков СБП.
`bank_bic`	string	Условно	БИК из списка банков. Обязателен, если его требует банк-эквайер. Уточняйте у менеджера.
`phone`	string	Да	Номер телефона получателя: 11 цифр, без `+`, пробелов, скобок и разделителей. Пример: `79999999999`.
`fio`	string	Нет	ФИО получателя. Используется вместе с `fio_check` для проверки совпадения с данными НСПК.
`fio_check`	boolean	Нет	`true` — проверить совпадение `fio` с ФИО, полученным от НСПК.
`description`	string	Нет	Назначение предполагаемой выплаты. По умолчанию — `выплата`. Итоговая строка вместе с префиксом магазина — не более 110 символов.

Проверка ФИО

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

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

Пример

JSONcURL

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

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

Ответ

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

2004004034044225XX

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

{
  "request_id": "check-req-20260811-0001"
}

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

Параметр	Тип	Описание
`request_id`	string	Идентификатор зарегистрированной проверки. Используется для получения её статуса.

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

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

Пример ответа 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": "Магазин не найден"
    }
  ]
}

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

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

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

Проверьте X-Api-Key и контур запроса.
Повторите запрос только после исправления ключа или URL контура.

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

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

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

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

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

При 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 и передайте время запроса, магазин и пример тела запроса.