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

Возвращает статус ранне созданной проверки реквизитов получателя через СБП.

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

Вызовите проверку возможности выплаты и сохраните request_id из ответа 200.
Сформируйте подпись по request_id и отправьте GET-запрос статуса.
При processing повторяйте тот же GET-запрос с тем же request_id; новую проверку для опроса не создавайте.
При success используйте полученные реквизиты при создании выплаты. При error обработайте error_message и исправьте реквизиты до новой проверки.

Интервал опроса

Рекомендуемый интервал между запросами статуса — не менее 5 секунд.

URL

ProductionStage

GET https://api.pay.kvell.group/v1/orders/payout/sbp/check/status/{request_id}

GET https://api.pay.stage.kvell.group/v1/orders/payout/sbp/check/status/{request_id}

Запрос

Path-параметры

Параметр	Тип	Обязательно	Описание
`request_id`	string	Да	Идентификатор из ответа метода проверки возможности выплаты.

Заголовки

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

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

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

SHA256(X-Api-Key + request_id + secret_key)

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

Пример

curl --request GET \
  --url 'https://api.pay.stage.kvell.group/v1/orders/payout/sbp/check/status/check-req-20260811-0001' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000' \
  --header 'X-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'

Ответ

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

2004004034044225XX

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

{
  "status": "success",
  "fio_nspk": "ИВАНОВ ИВАН ИВАНОВИЧ",
  "nspk_id": "A4073090444266160000040011200102",
  "error_message": "",
  "recipient_account": "40817***************"
}

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

Параметр	Тип	Описание
`status`	string	Состояние проверки. Возможные значения приведены в разделе «Статусы проверки».
`fio_nspk`	string \| null	ФИО, полученное от НСПК.
`nspk_id`	string \| null	Ссылка НСПК, которую может потребоваться передать в запросе выплаты.
`error_message`	string \| null	Причина отказа при `status: error`, полученная от банка или НСПК. Возможные значения приведены ниже.
`recipient_account`	string \| null	Маскированный счёт получателя, если банк вернул его.

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

При processing повторите этот GET-запрос с тем же request_id с интервалом не менее 5 секунд.
При success используйте полученные реквизиты согласно требованиям метода выплаты через СБП.
При error обработайте error_message; выплату по непроверенным реквизитам не создавайте.

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

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

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

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

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

Исправьте причину из errors[].message. При 20002 проверьте request_id, порядок значений в подписи и секретный ключ магазина.
Сформируйте правильный X-Signature и безопасно повторите тот же GET-запрос.

Пример ответа 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": "x-signature: Field required"
    }
  ]
}

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

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

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

Исправьте поля или заголовки, указанные в errors[].message.
Сформируйте подпись по фактическому request_id и безопасно повторите GET-запрос.

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

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

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

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

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

Безопасно повторите тот же GET-запрос с теми же request_id, X-Api-Key и X-Signature.
При повторяющейся ошибке обратитесь в поддержку KVELL и передайте URL, время запроса, HTTP-код, code и message без секретного ключа и подписи.

Статусы проверки

Статус	Финальный	Что делать
`processing`	Нет	Результат ещё не готов. Повторите этот GET-запрос с тем же request_id; не создавайте новую проверку на каждом опросе.
`success`	Да	Проверка завершена. Используйте полученные реквизиты при создании выплаты.
`error`	Да	Проверка не пройдена, выплата не может быть отправлена по реквизитам.

Справочные данные

Возможные значения `error_message`

KVELL возвращает в error_message сообщение, полученное от банка или НСПК. Перечень не является закрытым: банки и НСПК могут добавлять новые сообщения или изменять формулировки существующих.

Значение `error_message`	Что означает и что проверить
Недостаточно средств на счете {account}	Недостаточно средств.
Превышена разрешенная длина поля ustrd ("Описание платежа"). Разрешенная длина - {N} символов	Слишком длинное описание платежа.
Запрещены переводы на нерезидентов для данного клиента	Запрещены переводы на нерезидентов.
Значения параметров запроса не совпадают с данными предыдущего шага	Проверьте данные, повторите платёж.
Ошибка логики в СБП: Найден больше чем один Получатель	Получателю необходимо обратиться в свой банк.
Ошибка логики в СБП: Не найден Получатель	Получатель в СБП не найден.
Несовпадение ФИО получателя	Проверьте ФИО получателя.
Ошибка логики в СБП: Получатель отказался от получения средств через СБП	Получателю необходимо обратиться в свой банк.
Ошибка логики в СБП: Ограничения законодательства - уровень идентификации денежных средств недостаточен	Получателю необходимо обратиться в свой банк.
Ошибка логики в СБП: Получатель не дал согласие на получение средств через СБП	Получателю необходимо обратиться в свой банк.
Ошибка логики в СБП: OPKC_REJECT_COMMON	Системная ошибка.
Ошибка логики в СБП: EBD 20 has incorrect format (phone)	Проверьте формат телефона получателя: он должен быть `79991111111`.
Ошибка логики в СБП: The transfer amount (44) exceeds the maximum allowed value	Превышен лимит перевода.
Ошибка логики в СБП: Счет Получателя не найден	Получателю необходимо обратиться в свой банк.
Ошибка логики в СБП: OPKC_TIMEOUT	Обычно это означает, что НСПК не получила ответ от банка получателя (банк получателя был недоступен по СБП в момент операции).
Превышен лимит на сумму платежа в месяц. Сумма платежа не может быть выше ... руб.	Превышен лимит перевода.
Превышен лимит на сумму платежа на получателя в месяц. Сумма платежа не может быть выше 109991 руб	Превышен лимит перевода.
OPKC_REJECT_SUSPECTED_FRAUD	Противодействие массовым выводам денежных средств. ОПКЦ СБП имеет право приостанавливать операции СБП на основании признаков переводов денежных средств без согласия клиента и моделей оценки риска операций, устанавливаемых Банком России. Мониторингу и потенциальной блокировке подлежат: — случаи выявления групповых операций СБП в пользу одного получателя за определённый период времени; — случаи выявления групповых операций СБП со счёта одного отправителя за определённый период времени; — случаи выявления массового вывода денежных средств в пользу банка получателя за определённый период времени; — случаи выявления массового вывода денежных средств из банка отправителя за определённый период времени.
Описание платежа может содержать только символы из диапазонов U+0020 - U+007E, U+0410 - U+044F, U+0401, U+0451, U+2116 в Unicode	Нужно проверить, что передали в описании (назначении) платежа. Например, это может быть буква Ё.

Маска счёта получателя

recipient_account зависит от банка получателя и может быть null или пустой строкой. Поле заполняется, если операция выполняется через канал Альфа-Банка или Банка ПСБ.

В рамках используемых банковских каналов маску можно интерпретировать следующим образом:

Префикс	Описание
`40817...`	Текущий счёт физического лица. Обычно используется как признак полной идентификации получателя
`40820...`	Счёт физического лица-нерезидента
`423...`	Депозитный счёт (вклад) физического лица
`409...`	Счёт для операций с электронными денежными средствами или виртуальной картой. Не подтверждает полную идентификацию получателя
`30232...`	Транзитный счёт для незавершённых расчётов. Не является личным счётом получателя и не подтверждает его полную идентификацию

Счёт с полной идентификацией можно определить по первым трём цифрам 408 — это счета физических лиц. Следующие две цифры уточняют, кому принадлежит счёт:

02 — счета индивидуальных предпринимателей;
17 — текущие счета физических лиц-резидентов;
20 — текущие счета физических лиц-нерезидентов.

Маска не гарантирует уровень идентификации

Банк получателя может зачислять средства через общий счёт, возвращать номер электронного кошелька или не возвращать recipient_account. Поэтому поле следует использовать только как дополнительный признак. Решение о разрешении или запрете выплаты по отдельным типам счетов должно быть согласовано для конкретного банка-эквайера. В частности, на стороне KVELL может быть настроен запрет выплат на счета с префиксом 409.

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

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

URL

Запрос

Path-параметры

Заголовки

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

Пример

Ответ

Статусы проверки

Справочные данные

Возможные значения error_message

Маска счёта получателя

Возможные значения `error_message`