Интеграция Яндекс Пэй и Сплит через RBS

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

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

Такой способ интеграции упрощает подключение Яндекс Пэй в ваш магазин и позволяет одновременно работать с несколькими платежными методами и банками через один интерфейс.

Как подключить

Зарегистрируйтесь в личном кабинете Яндекс Пэй и подайте заявку на подключение сервиса Яндекс Пэй и Сплит в ваш магазин.
Перейдите на сайт business.rbspayment.ru и нажмите Подключить, чтобы зарегистрироваться в Платежном сервисе Роутер. В результате регистрации вы получите:
- адрес API Платежного сервиса;
- логин и пароль для отправки API-запросов.
После регистрации в Платежном сервисе в настройках укажите Яндекс Банк — оплата с помощью Яндекс Пэй и Сплит всегда производится через него. Текущие настройки можно узнать, отправив запрос /settings/getRouterParams.do.

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

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

Покупатель инициирует покупку товара или услуги на сайте.
Партнер отправляет в Платежный сервис Роутер один из следующих запросов на регистрацию заказа:
- /register.do — для одностадийной оплаты;
- /registerPreAuth.do — для двухстадийной оплаты.
Подробнее о видах оплаты см. в документации RBS в разделе Двухстадийные платежи.

Важно

На стороне Яндекс Банка один API-ключ дает возможность использовать или одностадийные, или двухстадийные платежи. Чтобы использовать в Платежном сервисе Роутер оба типа оплаты, получите в личном кабинете Яндекс Пэй два API-ключа для каждого типа оплаты и передайте их в службу поддержки Платежного сервиса.

Особенности запроса регистрации заказа
- При регистрации заказа можно указать, какие способы оплаты Яндекс Пэй и Сплит будут доступны покупателю: только карта, только Сплит или оба способа.
  
  Для этого передайте дополнительный параметр yandex_paymentWay. По умолчанию, если параметр не передан, доступна только оплата картой (CARD). Доступность тех или иных способов оплаты Яндекс Пэй и Сплит вы должны согласовать с Яндекс Банком.
- При регистрации заказа на оплату обязательно нужно передать корзину товаров — объект orderBundle. Если корзина не передана, но есть clientId, то запрос будет обработан как создание связки, см. Связки с Яндекс Пэй и Сплит.
Пример запроса
```
curl -X POST 'https://api.router.rbsuat.com/v1/register.do' -H 'Content-Type: application/json' \
--data-raw '{
    "orderNumber": "order_123508",
    "jsonParams": {
        "yandex_paymentWay": "CARD, SPLIT"
    },
    "amount": 10000,
    "currency": "643",
    "language": "ru",
    "returnUrl": "https://mybestmerchantreturnurl.com/success",
    "failUrl": "https://mybestmerchantreturnurl.com/fail",
    "userName": "test_user",
    "password": "test_user_password",
    "orderBundle": {
        "cartItems": {
        "items": [
            {
                "itemAmount": 10000,
                "itemCode": "123code",
                "itemCurrency": "643",
                "itemPrice": 10000,
                "name": "item 1",
                "positionId": "1",
                "quantity": {
                    "measure": "pcs",
                    "value": "1"
                }
            }
        ]
        }
    }
}'
```
Платежный сервис Роутер проверяет данные и регистрирует заказ.

Шаг 2. Запрос на оплату Яндекс Пэй и Сплит

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

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

{
    "errorCode": "0",
    "formUrl": "https://router.rbsuat.com/wl/payment.html?mdOrder=f9584546-2613-4a0d-896f-0194d243865f&language=ru",
    "orderId": "f9584546-2613-4a0d-896f-0194d243865f",
    "orderNumber": "order_123508"
}

Партнер направляет в Платежный сервис Роутер запрос на оплату заказа с помощью Яндекс Пэй и Сплит /yandex-box/paymentOrder.do.

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

curl -X POST 'https://api.router.rbsuat.com/v1/yandex-box/paymentOrder.do' \
-H 'Content-Type: application/json' \
--data-raw '{
    "orderId": "1f3224c9-cc80-4c2a-8ef7-ca4d198f6a2e",
    "password": "test_user_password",
    "userName": "test_user" 
}'

Платежный сервис Роутер запрашивает URL страницы оплаты в Яндекс Банке.
Яндекс Банк передает URL страницы оплаты Платежному сервису.

Шаг 3. Перенаправление на страницу оплаты

Платежный сервис передает URL страницы оплаты.

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

{
    "data": {
        "gwId": "YANDEX",
        "gwOrderId": "ffc65a85-1af5-7a4d-ab65-a29206c90f80",
        "orderId": "14f8b21d-46ab-11f0-8452-696e1279ae2c",
        "redirect": "https://sandbox.pay.ya.ru/l/k774SQ"
    },
    "success": true
}

Партнер перенаправляет покупателя на страницу оплаты Яндекс Пэй и Сплит — URL из параметра redirect.
Покупатель оплачивает заказ на странице Яндекс Пэй и Сплит любым из доступных способов.
Яндекс Банк перенаправляет покупателя на на URL для возврата.

Шаг 4. Финальный статус заказа

Опционально. Если настроены уведомления обратного вызова (callback), Яндекс Банк сообщает магазину результат оплаты.
Опционально. Если callback не настроен, партнер периодически отправляет в Платежный сервис Роутер запрос для получения финального статуса заказа /getOrderStatusExtended.do, используя query-параметр orderId. До тех пор, пока результат оплаты не станет известен, статус заказа будет PENDING.
Платежный сервис Роутер запрашивает в Яндекс Банке и передает партнеру статус заказа. Когда статус изменится, партнер отображает его на финальной странице.

Связки с Яндекс Пэй и Сплит

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

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

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

Важно

У вас должно быть разрешение на использование связок и соответствующие настройки в Яндекс Банке.

Создание связок Яндекс Пэй и Сплит возможно только при одностадийной оплате.

eCom-связка

Чтобы создать eCom-связку, нужно провести оплату Яндекс Пэй и Сплит, как описано выше, со следующими отличиями:
- добавить параметр clientId в запросе на регистрацию заказа;
- не передавать корзину товаров orderBundle.
Сумма в параметре amount будет игнорироваться, списание средств не произойдет.

Пример запроса:
```
curl -X POST 'https://api.router.rbsuat.com/v1/register.do' -H 'Content-Type: application/json' \
--data-raw '{
    "clientId": "12555",
    "orderNumber": "order_123508",
    "jsonParams": {
        "yandex_paymentWay": "CARD, SPLIT"
    },
    "amount": 10000,
    "currency": "643",
    "language": "ru",
    "returnUrl": "https://mybestmerchantreturnurl.com/success",
    "failUrl": "https://mybestmerchantreturnurl.com/fail",
    "userName": "test_user",
    "password": "test_user_password"
}'
```
Затем после оплаты покупатель должен будет подтвердить создание связки — привязать свою карту к магазину.

Чтобы узнать идентификатор созданной связки bindingId после завершения оплаты, вы можете настроить соответствующий callback, либо отправить запрос статуса заказа /getOrderStatusExtended.do.

Рекуррентная связка

Чтобы создать рекуррентную связку, необходимо провести оплату Яндекс Пэй и Сплит, как описано выше, но добавить в запрос регистрации заказа на шаге 2 следующие параметры:

clientId
recurringFrequency
recurringExpiry

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

curl -X POST 'https://api.router.rbsuat.com/v1/register.do' -H 'Content-Type: application/json' \
--data-raw '{
    "clientId": "12555",
    "jsonParams": {
        "yandex_paymentWay": "CARD, SPLIT",
        "recurringFrequency":12,
        "recurringExpiry":"20251225"
    },
    "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",
    "orderBundle": {
        "cartItems": {
        "items": [
            {
                "itemAmount": 1234,
                "itemCode": "123code",
                "itemCurrency": "643",
                "itemPrice": 1234,
                "name": "item 1",
                "positionId": "1",
                "quantity": {
                    "measure": "pcs",
                    "value": "1"
                }
            }
        ]
        }
    }
}'

Затем после оплаты покупатель должен будет подтвердить создание связки — оформить подписку.

Чтобы узнать идентификатор созданной связки bindingId после завершения оплаты, вы можете настроить соответствующий callback, либо отправить запрос статуса заказа /getOrderStatusExtended.do.

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