Схема интеграции: оплата картой¶

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

Последовательность вызовов API совпадает со схемой оплаты через Сплит. Единственное отличие — параметр availablePaymentMethods со значением ["CARD"], отключающий выбор рассрочки.

Подготовка к интеграции¶

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

Обратите внимание

Callback URL указывается без эндпоинта /v1/webhook.

Пошаговый процесс подключения¶

Шаг 1. Подключите библиотеку на фронтенде¶

Добавьте скрипт Web SDK Яндекс Пэй на страницы интернет-магазина:

<script src="https://pay.yandex.ru/sdk/v1/pay.js" onload="onYaPayLoad()" async></script>

Шаг 2. Разместите бейджи и виджеты в интерфейсе¶

Чтобы проинформировать покупателей, добавьте в HTML-код страниц DOM-контейнеры:

Рядом с ценой каждого товара разместите умные бейджи.
Под кнопкой покупки разместите виджет.
Отрисуйте вариант «Банковская карта».

Важно

При инициализации элементов Web SDK передайте параметр availablePaymentMethods: ["CARD"]. Это отключает отображение информации о рассрочке/Сплите.

Шаг 3. Инициируйте оплату (Frontend → Backend)¶

Когда покупатель выбирает «Яндекс Пэй» и нажимает «Оплатить», передайте с фронтенда на бэкенд магазина запрос с составом корзины и суммой.

Шаг 4. Создайте заказ через API (Backend → Яндекс Пэй)¶

Отправьте с бэкенда магазина авторизованный HTTP-запрос к Яндекс Пэй, чтобы создать платёжную сессию:

Метод: POST https://pay.yandex.ru/api/merchant/v1/orders
Заголовки: Authorization: Api-Key <API-ключ мерчанта>
Тело запроса: передайте данные корзины, итоговую сумму и параметр availablePaymentMethods: ["CARD"], чтобы ограничить способы оплаты.
Результат: Яндекс Пэй возвращает ссылку на платёжную форму в поле paymentUrl внутри объекта data.

Шаг 5. Перенаправьте покупателя на форму оплаты (Frontend → Яндекс Пэй)¶

Верните полученный paymentUrl с бэкенда на фронтенд.
Перенаправьте покупателя на защищённую форму оплаты Яндекса для ввода данных карты.

Шаг 6. Подтвердите оплату по вебхуку (Яндекс Пэй → Backend)¶

После успешного списания средств Яндекс Пэй отправляет асинхронный POST-запрос на Callback URL магазина.

В запросе передаётся JWT-токен со событием ORDER_STATUS_UPDATED и статусом заказа order.paymentStatus: "CAPTURED".
Проверьте цифровую подпись JWT-токена с помощью публичных ключей Яндекса (JWK), сверьте merchantId и обновите статус заказа на «Оплачен».
Ответьте Яндексу:
- При успехе: верните 200 OK с телом {"status": "success"}.
- При ошибке: верните 400 Bad Request с кодом ошибки. Если Яндекс не получает статус 200 OK, нотификация будет повторно отправляться в течение 24 часов.

Шаг 7. Проведите возврат (Backend → Яндекс Пэй)¶

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

Эндпоинт: POST https://pay.yandex.ru/api/merchant/v2/orders/{order_id}/refund
Заголовки: Authorization: Api-Key <API-ключ мерчанта>
Параметры тела запроса (Body):
- externalOperationId — уникальный ID операции на стороне магазина, выполняющий роль токена идемпотентности (защищает от дублирования возвратов при сетевых сбоях).
- refundAmount — сумма возврата (минимум 1 рубль). Для полного возврата достаточно передать только его.
- refundCart (при частичном возврате) — список конкретных позиций (productId, quantityCount, price) для возврата. При полном возврате передавать не требуется. Вместе с refundCart передавайте externalOperationId, чтобы не было повторного возврата за позиции.
- Альтернативный способ. targetCart — целевое состояние корзины, т.е. остаток товара у покупателя после возврата.
Результат исполнения:
- Синхронный ответ: возвращает 200 OK со статусом операции PENDING.
- Асинхронные вебхуки: после обработки банком отправляются два нотификационных запроса на Callback URL:
  - OPERATION_STATUS_UPDATED — со статусом операции SUCCESS;
  - ORDER_STATUS_UPDATED — со статусом заказа PARTIALLY_REFUNDED (если остались позиции) или REFUNDED (при полном возврате).

Нельзя передавать refundCart и targetCart одновременно

Это два взаимоисключающих способа описать частичный возврат. Выберите один из них.