Оплата Yandex Paybox через API

Платежный сервис Роутер поддерживает оплату Yandex Paybox через API. Способ оплаты Yandex Paybox позволяет оплатить заказ с помощью Яндекс Пей или Яндекс Сплит. Оплата выполняется на платежной странице Яндекса, URL которой предоставляет сервис Yandex Paybox.

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

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

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

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

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

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

register.do для одностадийной оплаты, или
registerPreAuth.do для двухстадийной оплаты.

Подробнее об этих видах оплаты см. в разделе Двухстадийные платежи.

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

Особенности запроса регистрации заказа:

При регистрации заказа Партнер может указать, какие способы оплаты Yandex Paybox будут доступны Клиенту: только карта, только Сплит или оба способа. Для этого передается дополнительный параметр yandex_paymentWay. По умолчанию, если параметр не передан, доступна только оплата картой (CARD). Доступность тех или иных способов оплаты Yandex Paybox Партнер должен согласовать с Яндекс Банком.
При регистрации заказа на оплату обязательно нужно передать корзину товаров — объект orderBundle. Если корзина не передана, но есть clientId, то запрос будет обработан как создание связки, см. Создание связки с Yandex Paybox.

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

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"
                }
            }
        ]
        }
    }
}'

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

Запрос на оплату Yandex Paybox

4. Платежный сервис Роутер передает Партнеру идентификатор созданного заказа 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"
}

5. Партнер направляет в Платежный сервис Роутер запрос на оплату данного заказа с помощью Yandex Paybox /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" 
}'

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

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

Перенаправление на страницу оплаты Яндекса

8. Платежный сервис передает 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
}

9. Партнер перенаправляет Клиента на страницу оплаты Yandex Paybox (URL из параметра redirect).

10. Клиент оплачивает заказ на странице Yandex Paybox любым из доступных способов (карта или Сплит).

11. Яндекс Банк перенаправляет Клиента на URL для возврата.

Финальный статус заказа

12. (Опция) Если настроены уведомления обратного вызова (callback), Яндекс Банк сообщает Партнеру результат оплаты.

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

14-17. Платежный сервис Роутер запрашивает в Яндекс Банке и передает Партнеру статус заказа. Когда статус изменится, Партнер отображает его на финальной странице.

Связки с Yandex Paybox

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

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

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

Создание обычной eCom-связки Yandex Paybox

Для создания eCom-связки нужно провести оплату Yandex Paybox, как описано выше, со следующими отличиями:

добавить параметр clientId в запросе на регистрацию заказа на шаге 2;
не передавать корзину товаров 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"
}'

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

Затем на шаге 12 Клиент должен будет подтвердить создание связки (привязку карты).

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

Создание рекуррентной связки Yandex Paybox

Для создания рекуррентной связки необходимо провести оплату Yandex Paybox, как описано выше, но добавить в запрос регистрации заказа на шаге 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"
                }
            }
        ]
        }
    }
}'

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

Затем на шаге 12 Клиент должен будет подтвердить создание связки (подписки).

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

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

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