Оплата SberPay через API

Платежный сервис Роутер поддерживает оплату SberPay через API по сценариям app2app и back2app. До появления поддержки этого способа оплаты другими банками-эквайерами, оплата SberPay возможна только в Сбербанк.

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

app2app

Этот сценарий используется при оплате в мобильном приложении Партнера. Для оплаты будет открыто мобильное приложение Сбербанк Онлайн (СБОЛ), а после подтверждения оплаты Клиент вернется в приложение Партнера.

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

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

1. Клиент инициирует покупку товара или услуги на сайте Партнера.

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

В jsonParams заказа указываются следующие параметры:

app2app=true — флаг, определяющий тип оплаты.
app.osType — тип операционной системы мобильного устройства пользователя (ios, android)
app.deepLink — ссылка на приложение партнера для возврата с успешным ответом из банка.

Также нужно указать номер телефона клиента.

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

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",
    "phone":"+79991234567",
    "jsonParams": {
        "app2app": true,
        "app.osType": "ios",
        "app.deepLink": "myapp://sberpay"
    }
}'

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

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

5. Банк регистрирует заказ. Выполняются необходимые операции для создания заказа в СБОЛ.

6. Банк возвращает в Платежный сервис Роутер данные заказа.

7. Платежный сервис Роутер возвращает результат регистрации заказа. При успешной регистрации в СБОЛ в ответе присутствует блок externalParams, в котором присутствует deepLink на МП СБОЛ.

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

{
    "errorCode": "0",
    "externalParams": {
        "sbolInactive": "false",
        "sbolBankInvoiceId": "XYpXsDoRiDYqvJlvkby8Cs0Lsk5mxF5h",
        "sbolDeepLink": "sberpay://invoicing/v2?bankInvoiceId=a67b0cedc9a44cfbbce3b9595afaafc1..."
    },
    "formUrl": "https://router.rbsuat.com/wl/payment.html?mdOrder=4ac083f4-91ea-11ef-a5e3-dff1b834a3a1&language=ru",
    "orderId": "4ac083f4-91ea-11ef-a5e3-dff1b834a3a1",
    "orderNumber": "order_123540"
}

Оплата заказа

8. Мобильное приложение Партнера открывает deepLink МП СБОЛ.

9. Клиент открывает приложение СБОЛ.

10. Клиент оплачивает заказ через СБОЛ.

11. СБОЛ сообщает статус заказа в банк.

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

12. Если настроены callback (см. Уведомления обратного вызова (callback)), Партнер ожидает и получает уведомление от банка об изменении статуса заказа.

13. Партнер запрашивает у Платежного сервиса статус заказа getOrderStatusExtended.do. В это время Клиент выполняет оплату через СБОЛ на своем устройстве.

Если callback настроены, запрос статуса выполняется однократно после получения уведомления об изменении статуса заказа.
Если callback не настроены, запросы статуса выполняются с некоторой периодичностью.

14-16. Платежный сервис Роутер запрашивает у банка и возвращает Партнеру статус заказа.

17. Партнер отображает клиенту результат операции на финальной странице.

back2app

В этом сценарии после запроса оплаты Клиент получит push-уведомление в приложении Сбербанк Онлайн (СБОЛ), где нужно будет подтвердить платеж.

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

sequenceDiagram autonumber participant Client as Клиент participant Merchant as Партнер participant Router as Платежный сервис Роутер participant Gateway as Сбер participant SBOL as МП СБОЛ Client -> Merchant: Начало покупки Merchant -> Router: Запрос регистрации заказа\n register.do (back2app=true) activate Router Router -> Router: Проверка данных, регистрация заказа. Router -> Gateway: Регистрация заказа\nregister.do (back2app=true) Gateway -> SBOL: Уведомление\n о заказе Gateway --> Router: Заказ зарегистрирован\n(+externalParams) Router --> Merchant: Заказ зарегистрирован в СБОЛ\n(+externalParams) Merchant --> Client: Редирект на страницу\nожидания результата deactivate Router Client -> Client: Открытие SBOL Client -> SBOL: Подтверждение оплаты SBOL -> Gateway: Изменение статуса\nзаказа alt Настроен callback Gateway -> Merchant: Нотификация об изменении\nстатуса заказа end Merchant -> Router: Запрос статуса заказа activate Router Router -> Gateway: Запрос статуса заказа Gateway --> Router: Статус заказа Router --> Merchant: Статус заказа deactivate Router Merchant -> Client: Редирект на страницу\nрезультата

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

1. Клиент инициирует покупку товара или услуги на сайте Партнера.

2. Партнер отправляет в Платежный сервис Роутер запрос на регистрацию заказа register.do. В jsonParams заказа передать флаг back2app=true. Также нужно указать номер телефона клиента.

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

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",
    "phone":"+79991234567",
    "jsonParams": {
        "back2app": true
    }
}'

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

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

5. Банк регистрирует заказ. Выполняются необходимые операции для создания заказа в СБОЛ.

6. Банк возвращает в Платежный сервис Роутер данные заказа.

7. Платежный сервис Роутер возвращает результат регистрации заказа. При успешной регистрации в СБОЛ в ответе присутствует блок externalParams.

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

{
    "errorCode": "0",
    "externalParams": {
        "sbolInactive": "false",
        "sbolBankInvoiceId": "kZntGl5xObR0TOETSQUncJ26DAfoSHGY"
    },
    "formUrl": "https://router.rbstest.ru/wl/payment.html?mdOrder=84c7cac5-91ec-11ef-a5e3-3d9def5f2628&language=ru",
    "orderId": "84c7cac5-91ec-11ef-a5e3-3d9def5f2628",
    "orderNumber": "order_123541"
}

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

8. Партнер переводит клиента на страницу инструкций по оплате и ожидания результатов оплаты.

9-17. Дальнейшие шаги выполняются аналогично сценарию app2app, см. Оплата заказа.

Связки с SberPay

Платежный сервис Роутер поддерживает связки с SberPay. Оплата по связке SberPay всегда направляется в Сбербанк.

Использование связок с SberPay возможно только для связок v1 при наличии соответствующего разрешения у Партнера в Сбербанке.

Создание связки с SberPay

Для создания связки нужно провести оплату SberPay, как описано выше, но добавить соответствующие параметры в запросе на регистрацию заказа register.do или registerPreAuth.do в зависимости от типа связки:

clientId для создания обычной eCom связки. Примеры см. на шаге 2 сценариев back2app и app2app.
clientId, recurringFrequency и recurringExpiry для рекуррентной связки. См. примеры ниже.

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

Пример регистрации заказа для создания рекуррентной связки SberPay с оплатой по API:

curl -X POST 'https://api.router.rbsuat.com/v1/v1/register.do' -H 'Content-Type: application/json' \
--data-raw '{
    "jsonParams": {
        "recurringFrequency": 15,
        "recurringExpiry": "20251018"
        "back2app": true
    },
    "orderNumber": "order_123463",
    "amount": 10000,
    "currency": "643",
    "language": "en",
    "returnUrl": "https://mybestmerchantreturnurl.com/",
    "userName": "test_user",
    "password": "test_user_password",
    "clientId": 1010123 
}'

После оплаты в ответ на запрос статуса заказа на шаге 13 вернется идентификатор созданной связки bindingId.

Пример регистрации заказа для создания рекуррентной связки SberPay с оплатой на платежной странице Платежного сервиса:

curl --location 'https://api.router.rbsuat.com/v1/register.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "allowedPaymentWays": [
        "CARD_BINDING",
        "CARD",
        "SBRF_SBOL"
    ],
    "jsonParams": {
        "recurringFrequency": 15,
        "recurringExpiry": "20251018"
    },
    "amount": 843,
    "clientId": "259753456",
    "currency": "643",
    "orderNumber": "1735280326_2991",
    "password": "test_user_password",
    "phone": "89001234567",
    "returnUrl": "https://mybestmerchantreturnurl.com/",
    "userName": "test_user"
}'

Идентификатор созданной связки можно получить в статусе заказа getOrderStatusExtended.do.

Оплата связкой с SberPay

Для оплаты связкой используются соответствующие методы:

paymentOrderBinding.do или instantPayment.do для оплаты обычной eCom связкой. Пример запроса см. здесь: Оплата eCom связкой по API.
recurrentPayment.do для оплаты рекуррентной связкой. Пример запроса см. здесь: Оплата рекуррентной связкой.