Оплата Яндекс Пэй через API

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

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

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

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

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

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

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

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

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

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

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

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

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

curl -X POST 'https://api.router.rbsuat.com/v2/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"
                }
            }
        ]
        }
    }
}'

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

Запрос на оплату Яндекс Пэй

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-box/paymentOrder.do.

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

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

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. Партнер перенаправляет Клиента на страницу оплаты Яндекс Пэй (URL из параметра redirect).

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

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

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

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

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

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

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

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

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

Создание связки с Яндекс Пэй

Создание обычной eCom-связки Яндекс Пэй

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

добавить параметр clientId в запросе на регистрацию заказа на шаге 2;
не передавать корзину товаров orderBundle.

Сумма в параметре amount будет игнорироваться, списание средств не произойдет.

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

curl -X POST 'https://api.router.rbsuat.com/v2/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"
}'

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).

Создание рекуррентной связки Яндекс Пэй

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

clientId
recurringFrequency
recurringExpiry

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

curl -X POST 'https://api.router.rbsuat.com/v2/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"
                }
            }
        ]
        }
    }
}'

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 Клиент должен будет подтвердить создание связки (подписки).

Оплата связкой Яндекс Пэй

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

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