RozetkaPay

Підписки

Створення та управління платними підписками через RozetkaPay API

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

Авторизація

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

  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": 99,
    "currency": "UAH",
    "platforms": ["platform_id"],
    "frequency_type": "monthly",
    "frequency": 1,
    "duration_periods": 12,
    "start_date": "2024-01-01T00:00:00Z"
  }'

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

ПараметрОбов’язковийОпис
nameТакНазва плану
priceТакЦіна плану: 30 = 30 грн
currencyТакВалюта (UAH)
frequency_typeТакТип періоду: daily, weekly, monthly, yearly
frequencyТакСкільки frequency_type в одному періоді оплати
duration_periodsТакСкільки frequency_type триває план
start_dateТакДата активації плану (RFC3339)
descriptionНіОпис плану
platformsНіПлатформи, що використовують план
callbacksНіПари API-ключ + URL для callback про зміни підписки
end_dateНіДата завершення плану

Приклади frequency

frequency_typefrequencyРезультат
daily2Кожні 2 дні
weekly1Щотижня
monthly1Щомісяця
monthly6Кожні 6 місяців
yearly1Щороку

Відповідь

Повертається створений план — його id використовуйте як plan_id при оформленні підписки:

{
  "id": "0fb23882-2845-49e7-9309-68aeee5d0d8f",
  "name": "Преміум підписка",
  "price": 99,
  "currency": "UAH",
  "state": "active",
  "frequency_type": "monthly",
  "frequency": 1,
  "duration_periods": 12,
  "start_date": "2024-01-01T00:00:00Z",
  "created_at": "2024-01-01T09:00:00Z"
}

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

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" \
  -u "login:password"

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

Оновити можна name, description, price, platforms, callbacks, frequency, frequency_type, duration_periods та end_date:

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НіЦіна: 30 = 30 грн (0 або не вказано — з плану)
trial_periodsНіКількість тріальних періодів

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

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

Відповідь

{
  "payment": {
    "id": "payment_123",
    "subscription_id": "sub_abc123",
    "details": {
      "amount": 99,
      "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": 99,
    "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": 1,
    "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Ціна за тріальний період
trial_periodsКількість тріальних періодів
use_plan_price_on_auto_renewПісля тріалу використовувати ціну плану

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

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

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}" \
  -u "login:password" \
  -H "X-CUSTOMER-AUTH: user_access_token"

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

Підписка одразу стає неактивною. Query-параметр refund=true додатково повертає кошти за поточний період:

curl -X DELETE "https://api.rozetkapay.com/api/subscriptions/v1/subscriptions/{subscription_id}/cancel?refund=true" \
  -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"

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

СтатусОпис
initСтворена, обробка не розпочата
processingВ обробці
pendingОчікує першої оплати
activeПідписка активна
inactiveПідписка неактивна

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

stateDiagram-v2
    [*] --> pending: Створення
    pending --> active: Перша оплата
    pending --> inactive: Помилка оплати

    active --> active: Продовження<br/>(auto_renew = true)
    active --> inactive: auto_renew = false<br/>Деактивація або скасування

    inactive --> [*]

Callbacks

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

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