Проведение платежа через СБП

Метод создаёт платёж через Систему быстрых платежей и возвращает ссылку для оплаты. Сумма, назначение платежа и дополнительные данные берутся из ранее созданной платёжной сессии. Результат платежа определяется позднее по статусу транзакции или колбэку.

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

Создайте платёжную сессию с уникальным transaction, суммой и описанием платежа.
Сформируйте подпись из X-Api-Key, transaction и secret_key, затем отправьте запрос на проведение платежа.
Получив 200, откройте form_url в браузере, в том числе на мобильном устройстве. Для оплаты с другого устройства сформируйте QR-код из значения form_url.
Определяйте результат платежа по статусу транзакции или используйте колбэк.

URL

ProductionStage

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

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

Запрос

Заголовки

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

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

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

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

secret_key находится в настройках магазина. Пробелы, переносы строк и другие разделители добавлять нельзя.

Тело запроса

Параметр	Тип	Обязательно	Описание
`transaction`	string	Да	Уникальный идентификатор транзакции в системе мерчанта. Должен совпадать с `transaction` из платёжной сессии.
`customer`	string \| null	Нет	Идентификатор плательщика, email или номер телефона.

Пример

JSONcURL

{
  "transaction": "payment-20260810-0001",
  "customer": "customer-42"
}

curl --request POST \
  --url 'https://api.pay.kvell.group/v1/orders/sbp' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Signature: <signature>' \
  --data '{
    "transaction": "payment-20260810-0001",
    "customer": "customer-42"
  }'

Ответ

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

2004004034044225XX

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

{
  "form_url": "https://qr.nspk.ru/AS100001234567890ABCDEF"
}

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

Параметр	Тип	Описание
`form_url`	string	Ссылка СБП для перехода в банковское приложение или формирования QR-кода.

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

Откройте form_url в браузере, в том числе на мобильном устройстве. Для оплаты с другого устройства сформируйте QR-код из полного значения form_url без изменений.
После действий плательщика получите статус транзакции или обработайте колбэк.

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

{
  "errors": [
    {
      "code": 20007,
      "message": "Транзакция совершалась прежде"
    }
  ]
}

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

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

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

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

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

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

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

Магазин не активен или ему запрещён доступ к API. Сессия не создана.

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

Проверьте статус магазина и повторите запрос только после восстановления доступа.

Пример ответа 404 (Not Found)

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

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

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

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

Магазин для переданного X-Api-Key не найден в выбранном контуре. Платёж не создан.

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

Проверьте X-Api-Key и контур Stage/Production.

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

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

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

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

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

Заголовки или тело запроса не прошли проверку обязательных полей и формата. Платёж не создан.

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

Исправьте поля из errors[].message, заново сформируйте подпись и повторите запрос с тем же transaction.

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

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

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

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

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

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

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

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

Привязка счёта

Требуется подключение рекуррентных платежей через СБП

Привязка счёта и последующие списания доступны только для транзакций, для которых включены рекуррентные платежи через СБП. Уточните доступность у менеджера KVELL.

Решение о привязке принимает плательщик в интерфейсе банка: он может подтвердить или отклонить привязку, а впоследствии самостоятельно отвязать счёт и запретить дальнейшие безакцептные списания.

Привязка без оплаты

При создании платёжной сессии передайте amount: 0, затем вызовите этот метод и направьте пользователя по form_url. В parent_transaction последующих списаний передавайте transaction операции привязки. После успешной привязки можно использовать метод рекуррентного платежа для безакцептного списания без присутствия клиента.

Привязка с оплатой

При создании платёжной сессии передайте amount больше 0, затем вызовите этот метод и направьте пользователя по form_url. В parent_transaction последующих списаний передавайте transaction операции привязки. После успешной привязки можно использовать метод рекуррентного платежа для безакцептного списания без присутствия клиента.