Поиск по ключевым словам
/

Оплата СБП через API

Общее описание

С помощью Платежного сервиса вы можете принимать платежи через СБП (Систему Быстрых Платежей) Национальной Системы Платежных Карт (НСПК). При использовании этого способа оплаты вместо ввода карточных данных на платежной странице в браузере клиент сканирует динамический QR-код и производит оплату. Если используется мобильное приложение, клиент нажимает на кнопку оплаты СБП и переходит по ссылке, выбирая приложение банка для оплаты.

Оплата с помощью СБП может маршрутизироваться в один или несколько целевых банков. Банки для СБП указываются в настройках партнера в Платежном сервисе. Поддерживается маршрутизация в процентном соотношении (например, 40% в банк А и 60% в банк Б), а также по некоторым параметрам платежа (сумма заказа, features заказа и т.п.).

Чтобы включить возможность принимать платежи через СБП, выбрать целевые банки и настроить критерии маршрутизации, обратитесь в службу технической поддержки. Текущие настройки можно узнать, отправив запрос /settings/getRouterParams.do.

Схема интеграции

Регистрация заказа

1. Клиент выбирает оплату через СБП на платежной странице Партнера или в мобильном приложении Партнера.

2. Партнер направляет в Платежный сервис Роутер запрос регистрации заказа: register.do для одностадийной оплаты или registerPreAuth.do для двухстадийной оплаты. Особенности двухстадийной оплаты с помощью СБП описаны в разделе Двухстадийная оплата и СБП.

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

curl --request POST \
'https://api.router.rbsuat.com/v1/register.do' \
-H 'Content-Type: application/json' \
--data-raw \
'{
    "orderNumber": "order_123473",
    "amount": 1234,
    "currency": "643",
    "language": "ru",
    "returnUrl": "https://mybestmerchantreturnurl.com/success",
    "userName": "test_user",
    "password": "test_user_password",
    "clientId":"client_10001"
}'

3. Платежный сервис Роутер проводит проверку входных данных и осуществляет регистрацию заказа.

4. Платежный сервис Роутер возвращает Партнеру номер зарегистрированного заказа.

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

{
    "errorCode": "0",
    "formUrl": "https://router.rbsuat.com/wl/payment.html?mdOrder=2dc811e7-8d1c-407a-bd25-a4f41f96cc60&language=en",
    "orderId": "2dc811e7-8d1c-407a-bd25-a4f41f96cc60",
    "orderNumber": "order_123457"
}

Запрос QR-кода

5. Партнер направляет в Платежный сервис Роутер запрос на генерацию QR-кода get.do, передавая полученный на предыдущем шаге номер заказа.

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

curl --request POST \
'https://api.router.rbsuat.com/v1/sbp_c2b/get.do' \
-H 'Content-Type: application/json' \
--data-raw \
'{
    "userName": "test_user",
    "password": "test_user_password",
    "mdOrder": "2c04379b-03ef-7e25-b619-446807dc54c2",
    "qrFormat": "image",
    "qrHeight": 10,
    "qrWidth": 10
}'

Здесь:

6. Платежный сервис Роутер осуществляет выбор банка. Маршрутизация выполняется по методу оплаты СБП, а не по банку-эмитенту карты.

7-10. Платежный сервис Роутер направляет в Банк запросы на регистрацию заказа и генерацию QR-кода. Банк регистрирует заказ и возвращает ответ с QR-кодом.

11. Платежный сервис Роутер возвращает Партнеру ответ на запрос генерации QR-кода. Если статус заказа qrStatus в значении STARTED, и в запросе были указаны qrHeight и qrWidth, то в ответе будет параметр renderedQr — непосредственно QR-код для отображения Клиенту.

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

{
"payload": "https://qr.nspk.ru/7eeee1bf3c784d0a8e593ab073bcac4b",
"renderedQr": "iVBORw0K...",
"qrId": "7eeee1bf3c784d0a8e593ab073bcac4b",
"qrStatus": "STARTED"
}

Оплата

12. В зависимости от того, где происходит оплата, действие на данном шаге может быть одним из следующих:

13. Клиент осуществляет оплату по QR-коду или в приложении выбранного банка.

Статус оплаты

В зависимости от настроек Партнера в банках для получения статуса оплаты может потребоваться либо отдельный запрос, либо принятие callback-уведомления.

Отправлять запросы статуса и ожидать callback следует в течение времени жизни заказа (30 минут, если иное не указано при регистрации). После этого срока QR-код будет отменен.

Партнер может сам отменить QR-код до истечения указанного срока с помощью метода reject.do, например, если Клиент решит выбрать другой способ оплаты или отменить покупку.

Запрос статуса

14. Партнер периодически направляет в Платежный сервис Роутер запрос статуса QR-кода status.do.

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

curl --request POST \
'https://api.router.rbsuat.com/v1/sbp_c2b/status.do' \
-H 'Content-Type: application/json' \
--data-raw \
'{
    "userName": "test_user",
    "password": "test_user_password",
    "mdOrder": "2c04379b-03ef-7e25-b619-446807dc54c2",
}'

15-16. Платежный сервис Роутер направляет в Банк запрос статуса QR-кода. Банк возвращает ответ со статусом QR-кода.

17. Платежный сервис Роутер возвращает Партнеру ответ на запрос статуса QR-кода. Если статус заказа transactionState свидетельствует о том, что оплата произведена (DEPOSITED), то можно перейти к шагу 19. Если статус CREATED, то нужно вернуться к шагу 14.

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

{
    "mdOrder": "f20a896f-07e8-492e-8c38-28c1ffe69124",
    "oldStatus": "STARTED",
    "payload": "https://qr.nspk.ru/106c2bfcbd904e0abd6197ac67dee2b6",
    "qrStatus": "STARTED",
    "qrType": "DYNAMIC",
    "transactionState": "CREATED",
    "transactionStateExtension": "SBP_C2B_STARTED"
}

Получение статуса в callback-уведомлении

18. Банк направляет Партнеру callback-уведомление по статусу заказа. Для использования callback-уведомлений у Партнера должны быть соответствующие разрешения в банке. Статические уведомления отправляются на тот адрес, который указан в настройках Партнера в банке. Динамические — на адрес, указанный в dynamicCallbackUrl при регистрации заказа. Подробнее см. на странице Уведомления обратного вызова (callback).

Отображение финального статуса заказа

19. Партнер отправляет в Платежный сервис Роутер запрос статуса операции getOrderStatusExtended.do.

20-22. Платежный сервис Роутер получает из банка и возвращает Партнеру финальный статус заказа.

23. Партнер перенаправляет Клиента на финальную страницу, где отображает результат оплаты.

Привязка счета через СБП (подписки)

СБП подписки — это механизм, позволяющий автоматически совершать регулярные платежи за услуги или товары без необходимости повторного ввода данных. Подписки используются для упрощения процесса оплаты, особенно для сервисов с регулярными платежами, таких как подписки на стриминговые сервисы, оплата коммунальных услуг и т.п.

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

Платежный сервис Роутер поддерживает следующие способы хранения данных связки:

Создание подписки СБП на стороне банка

Создание подписки возможно по API одним из следующих способов:

  1. При оплате заказа. В этом сценарии подписка будет создана только в случае, если клиент даст согласие на это в процессе оплаты.
  2. Отдельным заказом без оплаты. Этот сценарий специально предназначен для создания подписки.

Создание подписки СБП при оплате

Для создания подписки СБП с оплатой заказа:

  1. Партнер отправляет запрос на регистрацию заказа register.do или registerPreAuth.do. В запросе нужно передать параметры:

    • clientId — идентификатор клиента, для которого создается подписка.
    • дополнительный параметр subscritionPurpose — это может быть произвольное непустое значение.

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

    curl -X POST 'https://api.router.rbsuat.com/v1/register.do' -H 'Content-Type: application/json' \
--data-raw '{
    "orderNumber": "order_123508",
    "amount": 10000,
    "currency": "643",
    "language": "ru",
    "returnUrl": "https://mybestmerchantreturnurl.com/success",
    "failUrl": "https://mybestmerchantreturnurl.com/fail",
    "userName": "test_user",
    "password": "test_user_password",
    "clientId": "101023",
    "jsonParams": {
        "subscriptionPurpose": "test subscription"
    }
}'

  2. Когда клиент выберет оплату СБП, Партнер должен отправить запрос на получение QR-кода get.do. В запрос нужно добавить параметр createSubscription, свидетельствующий о необходимости создания подписки.

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

    curl -X POST 'https://api.router.rbsuat.com/v1/sbp_c2b/get.do' \
-H 'Content-Type: application/json' 
--data-raw '{
    "mdOrder": "861bf60b-ac9d-423c-9a23-94b2c4cb57dc",
    "qrFormat": "image",
    "qrHeight": 10,
    "qrWidth": 10,
    "userName": "test_user",
    "password": "test_user_password",
    "createSubscription": "true"
}'

В остальном процесс оплаты такой же, как при оплате по СБП через API.

Создание подписки СБП без оплаты

Для создания подписки без оплаты необходимо:

  1. В запросе на регистрацию заказа указать параметры:

    • clientId — идентификатор клиента.
    • "features": ["VERIFY"] — этот параметр дает зарегистрировать заказ с нулевой суммой. Использование такого значения Партнер должен предварительно согласовать с банком, который будет принимать платежи по СБП.
    • subscritionPurpose — назначение подписки, произвольная непустая строка.

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

    curl -X POST 'https://api.router.rbsuat.com/v1/register.do' -H 'Content-Type: application/json' \
--data-raw '{
    "orderNumber": "order_123527",
    "amount": 0,
    "currency": "643",
    "language": "ru",
    "returnUrl": "https://mybestmerchantreturnurl.com/success",
    "failUrl": "https://mybestmerchantreturnurl.com/fail",
    "userName": "test_user",
    "password": "test_user_password",
    "clientId": "101023",
    "features": ["VERIFY"],
    "jsonParams": {
        "subscriptionPurpose": "test subscription"
    }
}'

  2. В запросе на получение QR-кода get.do нужно добавить параметр createSubscription

    Пример запроса см. выше в сценарии создания подписки с оплатой.

В остальном процесс оплаты такой же, как при оплате по СБП через API.

Получение идентификатора созданной подписки

Идентификатор подписки, созданной на стороне банка, возвращается партнеру при запросе статуса заказа getOrderStatusExtended.do в параметре bindingId.

Список подписок СБП

Список всех подписок СБП можно получить методом /sbp_c2b/getBindings.do. Он возвращает активные СБП-подписки клиента и информацию по ним из всех банков, в которых у Партнера настроен прием СБП-платежей. Подписки СБП имеют тип "bindingType": "SBP_C2B".

Среди параметров подписки возвращается не только bindingId, но и параметры sbpSubscriptionToken и sbpMemberId. Их можно использовать для того, чтобы оплата подпиской маршрутизировалась в любой СБП-банк Партнера, а не только в тот, где создана связка — см. Оплата подпиской СБП.

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

curl -X POST 'https://api.router.rbsuat.com/v1/sbp_c2b/getBindings.do' -H 'Content-Type: application/json' \
--data-raw '{
    "userName": "test_user",
    "password": "test_user_password",
    "clientId": "101023"
}'

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

{
    "errorCode": "0",
    "bindings": [
     {
      "bankName": "Альфа Банк",
      "bindingId": "d8a8eeb8-67df-7fb8-9277-5b0d07dc54c2",
      "bindingType": "SBP_C2B",
      "clientId": "259753456",
      "createdDate": 1734521975150,
      "displayLabel": "Альфа Банк",
      "gwId": "BANKSOYUZ",
      "sbpMemberId": "100000000008",
      "sbpSubscriptionPurpose": "test sbp subscription",
      "sbpSubscriptionToken": "58c6ec02e3434130aeb7930a99a78552"
    }
    ]
}

Обратите внимание, что подписки СБП не возвращаются методом getBindings.do — он предназначен для остальных связок.

Оплата подпиской СБП

Перед вызовом метода оплаты нужно зарегистрировать новый заказ методом register.do или registerPreAuth.do, указав параметр description.

Оплата подпиской СБП возможна двумя способами:

Оплата по bindingId

Для оплаты по идентификатору подписки bindingId необходимо вызвать метод paymentOrderBinding.do, как для оплаты связкой. Такой платеж будет маршрутизирован в тот банк, где хранится подписка.

Получить bindingId можно после создания подписки или в списке подписок СБП.

Пример запроса см. здесь: Оплата eCom-связкой по API.

Оплата по sbpSubscriptionToken

Для оплаты по sbpSubscriptionToken необходимо вызвать метод paymentOrder.do. Такой платеж будет маршрутизирован в один из СБП-банков Партнера согласно настройкам маршрутизации.

В запросе обязательно передать параметры sbpSubscriptionToken и sbpMemberId. Их можно получить в списке подписок СБП.

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

curl --request POST --url 'https://api.router.rbsuat.com/v1/paymentOrder.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userName": "test_user",
    "password": "test_user_password",
    "mdOrder": "ec52097f-f9c5-42bc-8676-910c4066f1c1",
    "sbpMemberId": "110000000005",
    "sbpSubscriptionToken": "58c6ec02e3434130aeb7930a99a78552"
}'

Удаление подписки из банка

Для удаления подписки СБП можно использовать метод /sbp_c2b/unBind.do. Банк, в котором хранится подписка, определяется автоматически.

Хранение подписок СБП на стороне Партнера

Партнер может хранить параметры СБП-подписки sbpSubscriptionToken и sbpMemberId в своей системе. В этом случае он может использовать их для оплаты по sbpSubscriptionToken точно так же, как если бы они хранились в банке.

Двухстадийная оплата и СБП

Заказ считается двухстадийным, если для его регистрации был использован метод registerPreAuth.do.

СБП не поддерживает двухстадийные платежи, но оплата двухстадийных заказов по СБП через Платежный сервис возможна. Для этого требуется отдельное разрешение в банках, в которые вы направляете платежи по СБП. Это разрешение не сделает платеж двухстадийным, но дает возможность оплатить двухстадийный заказ с помощью СБП через редирект и по API.

Двухстадийный заказ, оплаченный с помощью СБП, сразу будет завершен — его статус будет DEPOSITED, а не APPROVED, как при обычной двухстадийной оплате. При этом средства будут сразу списаны со счета Клиента, для этого не нужно выполнять /deposit.do.

Для отмены такого заказа используется метод /refund.do

Пример

На автозаправке используется двухстадийная оплата, чтобы холдировать средства на счете клиента, а затем списать ту сумму, на которую действительно был залит бензин (она может отличаться от предавторизованной).

В приложении автозаправки клиент может оплачивать заказы картой и СБП. Заранее неизвестно, какой способ оплаты выберет клиент. Поэтому заказ регистрируется как двухстадийный, и после оплаты картой выполняются стандартные операции /deposit.do и /reverse.do. А если клиент решит оплатить заказ с помощью СБП, то средства сразу списываются со счета (/deposit.do не требуется), и для корректировки суммы используется /refund.do.

Категории:
router API V1
Категории
Результаты поиска
Навигация
Перейти
Закрыть
Категории
Результаты поиска