Рекурентні платежі

Рекурентні платежі дозволяють списувати кошти з картки клієнта без його повторної участі. На відміну від Підписок, цей сценарій не використовує плани та авторизацію користувача — достатньо зберегти recurrent_id після першого платежу і викликати endpoint повторного списання.

Коли використовувати

Сценарій	Інструмент
Прості повторні списання за однакову послугу без планів	Рекурентні платежі (цей гайд)
Плани, трейли, авторизація користувача, next_payment_date	Підписки

Крок 1. Ініціювання рекурентного платежу

На першому платежі передайте init_recurrent_payment: true:

curl -X POST https://api.rozetkapay.com/api/payments/v1/new \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 199,
    "currency": "UAH",
    "external_id": "order_init_1",
    "mode": "direct",
    "init_recurrent_payment": true,
    "callback_url": "https://your-site.com/callback",
    "customer": {
      "external_id": "user_123",
      "email": "user@example.com",
      "payment_method": {
        "type": "cc_token",
        "cc_token": { "token": "tok_abc", "use_3ds_flow": true }
      }
    }
  }'

У відповіді (та в callback після завершення 3DS) буде поле details.recurrent_id:

{
  "is_success": true,
  "details": {
    "status": "success",
    "amount": "199",
    "currency": "UAH",
    "recurrent_id": "rec_d9adbef7-b4b9-465d-bbd9-a565902e0b2d"
  }
}

Збережіть recurrent_id на вашому боці — він буде єдиним у рамках підписки платника.

Крок 2. Повторне списання

Для кожного наступного списання викликайте окремий endpoint:

curl -X POST https://api.rozetkapay.com/api/payments/v1/recurrent \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "recurrent_id": "rec_d9adbef7-b4b9-465d-bbd9-a565902e0b2d",
    "external_id": "order_monthly_042",
    "amount": 199,
    "callback_url": "https://your-site.com/callback"
  }'

Параметри

Параметр	Обов’язковий	Тип	Опис
`recurrent_id`	Так	string	ID рекурент-прив’язки, отриманий на першому платежі
`external_id`	Так	string	Унікальний номер цього замовлення
`amount`	Так	number	Сума списання
`callback_url`	Ні	string	URL для callback
`confirm`	Ні	boolean	За замовчуванням `true` — списати одразу. `false` — заблокувати, потім викликати `POST /api/payments/v1/confirm`
`payload`	Ні	string	Додаткові дані

Весь перелік полів — у API Reference →

Відповідь

Структура така сама, як у звичайному платежі. Див. Платіжні сценарії.

Двостадійні рекурентні списання

Якщо потрібно спочатку заблокувати суму, передайте confirm: false у запиті рекурентного списання та викличте POST /api/payments/v1/confirm так само, як у двостадійній оплаті.

Повернення та відміна

Повернення та скасування виконуються звичайними методами за external_id конкретного списання — див. Повернення коштів.

Callbacks

Кожне рекурентне списання генерує callback з тим самим форматом та підписом, що і звичайні платежі — див. Callbacks / Webhooks.