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

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

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

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

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

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

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

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

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

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

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

При регистрации заказа Партнер может указать, какие способы оплаты Яндекс Пэй будут доступны Клиенту: только карта, только Сплит или оба способа. Для этого передается дополнительный параметр 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. Платежный сервис Router проверяет данные Партнера и регистрирует заказ.

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

4. Платежный сервис Router передает Партнеру идентификатор созданного заказа 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. Партнер направляет в Платежный сервис Router запрос на оплату данного заказа с помощью Яндекс Пэй /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. Платежный сервис Router запрашивает 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 не настроен, Партнер периодически отправляет в Платежный сервис Router запрос для получения финального статуса заказа getOrderStatusExtended.do, используя query-параметр orderId. До тех пор, пока результат оплаты не станет известен, статус заказа будет PENDING.

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

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

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

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

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

Создание обычной 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 для оплаты рекуррентной связкой. Пример запроса см. здесь: Оплата рекуррентной связкой.