Підписки

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

Авторизація

Для роботи з підписками потрібна:

1. Авторизація платформи — Basic Auth (для всіх методів)
2. Авторизація користувача — заголовок X-CUSTOMER-AUTH з access-токеном (для методів роботи з підписками користувача)

Плани підписок

Створення плану

curl -X POST https://api.rozetkapay.com/api/subscriptions/v1/plans \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Преміум підписка",
    "description": "Доступ до всіх функцій",
    "price": 9900,
    "currency": "UAH",
    "platforms": ["platform_id"],
    "frequency_type": "monthly",
    "frequency": 1,
    "start_date": "2024-01-01T00:00:00Z"
  }'

Параметри плану

Параметр	Обов’язковий	Опис
name	Так	Назва плану
description	Так	Опис плану
price	Так	Ціна в копійках (9900 = 99 грн)
currency	Так	Валюта (UAH)
platforms	Так	Платформи, що використовують план
frequency_type	Так	Тип періоду: daily, weekly, monthly, yearly
frequency	Так	Кількість періодів
start_date	Так	Дата активації плану (RFC3339)
end_date	Ні	Дата завершення плану

Заувага

Ціна в межах 100–15000000 (1 грн – 150 000 грн)

Приклади frequency

frequency_type	frequency	Результат
daily	2	Кожні 2 дні
weekly	1	Щотижня
monthly	1	Щомісяця
monthly	6	Кожні 6 місяців
yearly	1	Щороку

Відповідь

{
  "plan_id": "0fb23882-2845-49e7-9309-68aeee5d0d8f"
}

Отримання плану

curl -X GET "https://api.rozetkapay.com/api/subscriptions/v1/plans/{plan_id}" \
  -u "login:password"

Отримання всіх планів

curl -X GET "https://api.rozetkapay.com/api/subscriptions/v1/plans?platform=platform_id" \
  -u "login:password"

Оновлення плану

Можна оновити тільки name та description:

curl -X PATCH "https://api.rozetkapay.com/api/subscriptions/v1/plans/{plan_id}" \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Новий преміум",
    "description": "Оновлений опис"
  }'

Деактивація плану

curl -X DELETE "https://api.rozetkapay.com/api/subscriptions/v1/plans/{plan_id}" \
  -u "login:password"

Обережно

Існуючі підписки залишаться активними до наступної оплати, після чого стануть неактивними.

Підписки користувачів

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

curl -X POST https://api.rozetkapay.com/api/subscriptions/v1/subscriptions \
  -u "login:password" \
  -H "X-CUSTOMER-AUTH: user_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "0fb23882-2845-49e7-9309-68aeee5d0d8f",
    "auto_renew": true,
    "callback_url": "https://your-site.com/subscription-callback",
    "result_url": "https://your-site.com/subscription-success",
    "description": "Підписка для user@example.com",
    "start_date": "2024-01-15T10:00:00Z",
    "customer": {
      "email": "user@example.com",
      "external_id": "user_123",
      "payment_method": {
        "type": "cc_token",
        "cc_token": {
          "token": "tok_card_token",
          "use_3ds_flow": true
        }
      }
    }
  }'

Параметри підписки

Параметр	Обов’язковий	Опис
plan_id	Так	ID плану
auto_renew	Ні	Автопродовження (true за замовч.)
callback_url	Так	URL для callbacks
result_url	Так	URL після успішної оплати
description	Так	Опис підписки
start_date	Так	Дата активації (RFC3339, UTC)
customer	Так	Дані користувача
customer.payment_method	Так	Платіжний метод
price	Ні	Ціна (якщо не вказано — з плану)
trial_periods	Ні	Кількість тріальних періодів

Платіжні методи для підписок

• cc_token — токен картки
• wallet — картка з гаманця
• google_pay — Google Pay
• apple_pay — Apple Pay

Відповідь

{
  "payment": {
    "id": "payment_123",
    "subscription_id": "sub_abc123",
    "details": {
      "amount": 9900,
      "currency": "UAH",
      "status": "success",
      "status_code": "subscription_successful"
    },
    "user_action": {
      "type": "url",
      "value": "https://pay.rozetkapay.com/3ds/..."
    }
  },
  "subscription": {
    "id": "sub_abc123",
    "plan_id": "0fb23882-2845-49e7-9309-68aeee5d0d8f",
    "state": "active",
    "auto_renew": true,
    "price": 9900,
    "currency": "UAH",
    "start_date": "2024-01-15T10:00:00Z",
    "next_payment_date": "2024-02-15T10:00:00Z"
  }
}

Тріальна підписка

Для створення тріальної підписки вкажіть:

curl -X POST https://api.rozetkapay.com/api/subscriptions/v1/subscriptions \
  -u "login:password" \
  -H "X-CUSTOMER-AUTH: user_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "0fb23882-2845-49e7-9309-68aeee5d0d8f",
    "price": 100,
    "trial_periods": 3,
    "use_plan_price_on_auto_renew": true,
    "auto_renew": true,
    "callback_url": "https://your-site.com/callback",
    "result_url": "https://your-site.com/result",
    "start_date": "2024-01-15T10:00:00Z",
    "customer": {
      "payment_method": {
        "type": "cc_token",
        "cc_token": {
          "token": "tok_card_token",
          "use_3ds_flow": true
        }
      }
    }
  }'

Параметр	Опис
price	Ціна за тріальний період (напр. 1 грн)
trial_periods	Кількість тріальних періодів
use_plan_price_on_auto_renew	Після тріалу використовувати ціну плану

Заувага

Якщо план має frequency_type=weekly, frequency=4 і trial_periods=3, наступний платіж буде через 12 тижнів.

Управління підписками

Отримання підписки

curl -X GET "https://api.rozetkapay.com/api/subscriptions/v1/subscriptions/{subscription_id}" \
  -u "login:password" \
  -H "X-CUSTOMER-AUTH: user_access_token"

Отримання всіх підписок користувача

curl -X GET "https://api.rozetkapay.com/api/subscriptions/v1/subscriptions" \
  -u "login:password" \
  -H "X-CUSTOMER-AUTH: user_access_token"

Оновлення підписки

Оновлення auto_renew:

curl -X PATCH "https://api.rozetkapay.com/api/subscriptions/v1/subscriptions/{subscription_id}" \
  -u "login:password" \
  -H "X-CUSTOMER-AUTH: user_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_renew": false
  }'

Деактивація підписки

Підписка залишається активною до next_payment_date:

curl -X DELETE "https://api.rozetkapay.com/api/subscriptions/v1/subscriptions/{subscription_id}/deactivate" \
  -u "login:password" \
  -H "X-CUSTOMER-AUTH: user_access_token"

Скасування підписки

Підписка одразу стає неактивною:

curl -X DELETE "https://api.rozetkapay.com/api/subscriptions/v1/subscriptions/{subscription_id}/cancel" \
  -u "login:password" \
  -H "X-CUSTOMER-AUTH: user_access_token"

Отримання платежів по підписці

curl -X GET "https://api.rozetkapay.com/api/subscriptions/v1/subscriptions/{subscription_id}/payments" \
  -u "login:password" \
  -H "X-CUSTOMER-AUTH: user_access_token"

Статуси підписок

Статус	Опис
active	Підписка активна
inactive	Підписка неактивна
pending	Очікує обробки

Діаграма життєвого циклу

┌─────────────────┐
│  Створення      │
│  підписки       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│    Оплата       │────▶│     Active      │
│   (успішна)     │     │                 │
└─────────────────┘     └────────┬────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
         │                       │ next_payment_date     │
         │                       │                       │
         │        auto_renew     ▼        auto_renew     │
         │        = true    ┌─────────┐   = false        │
         │         ┌────────│ Оплата  │────────┐         │
         │         │        └─────────┘        │         │
         │         ▼                           ▼         │
         │    ┌─────────┐                 ┌─────────┐    │
         │    │ Active  │                 │Inactive │    │
         │    │(renewed)│                 │         │    │
         │    └─────────┘                 └─────────┘    │
         │                                               │
         │  Deactivate           Cancel                  │
         ▼                       ▼                       │
┌─────────────────┐     ┌─────────────────┐              │
│  Деактивація    │     │  Скасування     │              │
│ (до next_date)  │     │   (одразу)      │              │
└────────┬────────┘     └────────┬────────┘              │
         │                       │                       │
         ▼                       ▼                       │
┌─────────────────────────────────────────────────────────┘
│                    Inactive
└─────────────────────────────────────────────────────────

Callbacks

При зміні статусу підписки або платежу надсилається callback:

{
  "subscription_id": "sub_abc123",
  "event": "payment_success",
  "payment": {
    "id": "payment_456",
    "amount": 9900,
    "currency": "UAH",
    "status": "success"
  },
  "subscription": {
    "state": "active",
    "next_payment_date": "2024-03-15T10:00:00Z"
  }
}