Перейти к содержанию

payments/qr/sbp/link - Получение ссылки на оплату через СБП

  • HTTP-метод: POST
  • URL: /payments/qr/sbp/link
  • Форма взаимодействия: Сервер-сервер
  • Формат тела запроса: application/json
  • Аутентификация: HTTP Basic Auth (PublicId / ApiSecret)
  • Назначение: получение платёжной ссылки для перенаправления клиента в мобильное приложение банка для оплаты через Систему быстрых платежей (СБП). Клиента нужно перенаправить на полученный URL — в приложении банка он подтвердит оплату.

URL

1
https://cloud.wallet.kvell.group/payments/qr/sbp/link

1
/payments/qr/sbp/link

Структура запроса

Поле Тип Обяз. Описание
PublicId str ✔ Идентификатор терминала, выданный при подключении. Дублирует логин из Basic Auth.
Amount decimal ✔ Сумма платежа в валюте, разделитель точка. Количество не нулевых знаков после точки — 2.
Currency str ✔ Валюта платежа.
Scheme str ✔ Схема проведения платежа. Единственное поддерживаемое значение — charge (одностадийная оплата).
Description str Назначение платежа в свободной форме.
AccountId str Идентификатор плательщика на стороне мерчанта.
Email str E-mail плательщика, на который будет отправлена квитанция об оплате.
InvoiceId str Номер счёта или заказа на стороне мерчанта.
JsonData json Любые другие данные, которые будут связаны с транзакцией.
SuccessRedirectUrl str URL для перенаправления клиента после успешной оплаты (до 1024 символов). После оплаты клиент будет перенаправлен на этот адрес из приложения банка.
IpAddress str IP-адрес плательщика.
Os str Операционная система устройства плательщика. Пример значения: Android, iOS, Windows.
Webview bool Признак открытия браузера в режиме webview.
Device str Признак устройства плательщика. Возможные значения: MobileApp, DesktopWeb, Mobile.
Browser str Название браузера клиента на основании userAgent.
TtlMinutes int Время в минутах, в течение которого будет доступна оплата по ссылке. От 1 до 129600 (90 дней).
SaveCard bool Признак сохранения карты, привязанной клиентом при оплате через СБП, для последующих списаний по токену.
IsTest bool Флаг тестового режима оплаты. По умолчанию false.

Структура ответа

Ответ содержит три составляющие: Success — результат запроса, Message — описание ошибки, Model — данные ответа.

Поле Success не отражает статус самой транзакции, а только успешность вызова API. Статус транзакции дополнительно можно узнать через колбэк.

Поле Тип Описание
Success bool Результат запроса.
Message string Описание ошибки (при неуспешном запросе).
Model.QrUrl string URL-адрес для перенаправления клиента в приложение банка.
Model.QrImage string Не заполняется данным методом (зарезервировано под получение QR-кода).
Model.TransactionId int Идентификатор транзакции.
Model.MerchantOrderId string Переданный InvoiceId.
Model.ProviderQrId string Идентификатор платёжной ссылки на стороне провайдера.
Model.Amount number Сумма платежа.
Model.Message string Техническое сообщение о состоянии транзакции.
Model.IsTest bool Флаг тестового режима оплаты.

Пример запроса

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "PublicId": "test_api_00000000000000000000002",
  "Amount": 1000,
  "Currency": "RUB",
  "Scheme": "charge",
  "Description": "Оплата по СБП",
  "AccountId": "email@email.com",
  "Email": "email@email.com",
  "InvoiceId": "order_no4009",
  "SuccessRedirectUrl": "https://merchant.ru/success"
}

Пример ответов

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "Model": {
    "QrUrl": "https://qr.nspk.ru/...",
    "QrImage": null,
    "TransactionId": 11122233344,
    "MerchantOrderId": "order_no4009",
    "ProviderQrId": "BB1S004HCK9PFD0F996RJI3208UE",
    "Amount": 10,
    "Message": "Created",
    "IsTest": false
  },
  "Success": true,
  "Message": null
}

1
2
3
4
{
  "Message": "Ошибка авторизации",
  "Success": false
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "Model": {
    "TransactionId": 11122233344,
    "Amount": 10,
    "InvoiceId": "order_no4009",
    "Status": "Declined",
    "StatusCode": 5,
    "ReasonCode": 5051,
    "CardHolderMessage": "Недостаточно средств на карте"
  },
  "Success": false,
  "Message": null
}

1
2
3
4
{
  "Message": "Scheme - Value error, Scheme must be 'charge'",
  "Success": false
}

Примечания

  • Структура Model, описанная выше (QrUrl, ProviderQrId и т.д.), соответствует только успешно созданной ссылке (Success: true). Если транзакция отклонена на стороне провайдера сразу при создании ссылки, Model вместо этого содержит общие данные транзакции — TransactionId, Status, StatusCode, ReasonCode, CardHolderMessage — без QrUrl (см. пример «Транзакция отклонена»).
  • Параметр Scheme поддерживает только значение charge — двухстадийная оплата через СБП не поддерживается.
  • Список кодов ошибок отклонённых транзакций — в разделе Коды ошибок.
  • Статусы транзакции описаны в разделе Статусы транзакции.
  • Для идемпотентных повторов запроса используйте заголовок X-Request-ID (см. Обзор).
  • Метод поддерживает повторную попытку оплаты тем же InvoiceId после отклонённой транзакции — см. раздел «Повторные попытки оплаты» в Обзоре.