Рекуррентные платежи

Рекуррентные платежи (автоплатежи) — это платежи, которые происходят регулярно или автоматически по инициативе продавца, без необходимости повторного ввода данных со стороны покупателя. Такая механика платежей подходит продавцам, которые предлагают подписку на свои товары или услуги.

Как это работает?

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

Этап 1. Оформление подписки

1. Настройте процесс формирования корзины товаров так, чтобы у покупателя была возможность выбрать вариант подписки и ее условия:

   • период в единицах измерения времени и их количество;
   • сумма следующих списаний;
   • наличие пробного периода (триала): до конкретной даты или период с единицей измерения.

2. Разместите кнопку оплаты Яндекс Пэй согласно общим рекомендациям. Нажатие на кнопку вызывает сallback на фронтенде партнера.

3. Настройте фронтенд магазина так, чтобы после нажатия кнопки оплаты Яндекс Пэй он создавал заказ на бэкенде магазина.

4. Настройте бэкенд магазина так, чтобы при выборе варианта подписки он передавал заказ в бэкенд Яндекс Пэй методом /subscriptions. В запросе должны быть параметры:

   Параметр и значение	Описание
   isBinding: false	Позволяет передавать данные о корзине и условиях подписки
   currencyCode: RUB	Трехбуквенный код валюты заказа
   orderId	Уникальный идентификатор заказа, будет использоваться в дальнейшем для списания средств
   redirectUrls	Ссылки для переадресации пользователя с формы оплаты. Обязательно для онлайн-магазинов
   cart	Данные корзины
   intervalCount	Количество периодов подписки в единицах времени, указанных в intervalUnit
   intervalUnit	Единица времени для периодичности подписки
   futureWriteOffAmount	Сумма, которая будет списываться в будущем
   trialUnit и trialCount	Пробный период, если есть (в единицах измерения времени и их количество)
   trialEndAt	Дата окончания пробного периода, если есть

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

5. В ответ бэкенд Яндекс Пэй вернет:

   • paymentUrl — ссылку на форму оплаты Яндекс Пэй. Настройте передачу этой ссылки на фронтенд магазина.
   • subscriptionId — идентификатор подписки. Используйте его для проверки привязки карты и получения информации по подписке.
   Пример ответа

   {
      "code": 200,
      "status": "success",
      "data": {
         "paymentUrl": "https://sandbox.pay.ya.ru/l/xxxxxx",
         "subscriptionId": "30b3579e-3baa-4a82-8fcc-02551b42ef40"
      }
   }
   

6. Настройте фронтенд магазина так, чтобы он транслировал полученную ссылку на оплату в SDK Яндекс Пэй.

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

   • для Web SDK: происходит перенаправление на полученную ссылку для оплаты;
   • для Mobile SDK: открывается формы для оплаты.

8. Покупатель приступает к оплате:

   1. Открывает ссылку на оплату.

   2. Авторизуется с Яндекс ID, если не был авторизован ранее.

   3. Выбирает способ оплаты и нажимает кнопку оплаты (в случае полной оплаты с кешбэком выбирает сохраненную в Яндексе карту или СБП-привязку к счету).

   4. При покупке товара или услуги с пробным периодом проходит процедуру привязки карты и подтверждает списание тестовой суммы (11 рублей) для проверки 3ds. Сумма (11 рублей) будет возращена после прохождения проверки.

9. Яндекс Пэй проводит платеж, списывая денежные средства с выбранной карты покупателя.

   Если оплата прошла успешно, заказ перейдет в статус CAPTURED. Отслеживать статус заказа можно через:

   Уведомления

   Для оповещения об изменениях статуса заказа или операции настройте обратный вызов (/webhook) от бэкенда Яндекс Пэй:

   1. Укажите публично доступный HTTPS URL-адрес бэкенда магазина в поле Callback URL в личном кабинете Яндекс Пэй в разделе Настройки.
   2. Настройте бэкенд магазина таким образом, чтобы он принимал запросы от бэкенда Яндекс Пэй. Подробнее о требованиях читайте в документации Merchant API.
   3. Посмотрите примеры нотификаций.
   Поллинг статуса заказа

   Настройте регулярную отправку запросов о статусе заказа /orders/{order_id} к бэкенду Яндекс Пэй.

   Возможные статусы заказа при проведении оплаты:

   PENDING	Оплата в процессе
   CAPTURED	Оплачен
   FAILED	Оплата не прошла. В этом случае в поле reason будет указана причина ошибки

10. Деньги за покупку поступят на следующие сутки.

    Примечание

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

Этап 2. Списание средств продавцом

Продавец инициирует списание денежных средств, если у клиента закончилась предыдущая подписка или завершился пробный период.

Для списания средств настройте бэкенд магазина так, чтобы после формирования корзины товаров он вызывал метод /subscriptions/recur и передавал в поле parentOrderId значение orderId, заданное ранее при привязке карты.

Сумма заказа будет списана с карты, привязанной ранее. Если операция прошла успешно, заказ перейдет в статус CAPTURED, а деньги за покупку поступят продавцу на следующие сутки.

Отслеживать статус заказа можно через:

Возможные статусы заказа при проведении оплаты:

Проверка привязки карты

Чтобы проверить, привязана ли карта к аккаунту в магазине или сервису, используйте метод /subscriptions/{customer_subscription_id}. В запросе передайте параметры:

• subscriptionId — идентификатор подписки, полученный при привязке карты в ответе на запрос /subscriptions;
• check_card_active: true — чтобы проверить привязку карты.

Если в ответе вернулся параметр isCardActive: null, то привязанных карт нет.

Возврат средств

Провести возврат можно двумя способами:

• в личном кабинете в разделе Платежи;
• при помощи запросов к API.

Минимальная сумма возврата — 1 рубль.

Статусы, которые мы высылаем в интеграции

Статусы платежа при проведении оплаты:

Статусы платежа при проведении возврата:

Статусы операций:

Примеры нотификаций

Оформление подписки

После оформления подписки методом /subscriptions вам придет одна нотификация ORDER_STATUS_UPDATED со статусом заказа (платежа).

Здесь orderId — идентификатор заказа, который вы передали при оформлении подписки.

{
  "event": "ORDER_STATUS_UPDATED",
  "eventTime": "2025-12-23T10:48:47.566064+00:00",
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "order": {
    "orderId": "order-inbv306r",
    "paymentStatus": "CAPTURED"
  }
}

{
  "event": "ORDER_STATUS_UPDATED",
  "eventTime": "2025-12-23T10:48:47.566064+00:00",
  "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
  "order": {
    "orderId": "order-inbv306r",
    "paymentStatus": "FAILED"
  }
}

Списание по подписке

После списания средств методом /subscriptions/recur вам придет несколько нотификаций.

Здесь:

• orderId — идентификатор заказа, который вы передали при списании средств по подписке;
• customerSubscriptionId — идентификатор подписки из ответа метода /subscriptions.

Сценарии тестирования механики

Для качественной работы сервиса протестируйте его в тестовой и боевой среде перед приемом платежей пользователей.

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