Перейти к содержанию

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

План подписки сообщает UnonaPay, как часто и в каком размере взимать оплату с клиентов. Торговцы могут создать неограниченное количество планов подписки для своих магазинов.

Каждый план имеет уникальный идентификатор, который необходимо передавать в запросах.


Создание плана

Запрос

Отправьте POST запрос на https://api.unonapay.com/plans со следующими параметрами:

Параметр Тип Описание
test boolean true или false. План будет тестовым, если значение true
title * обязательный
string Название подписки.
currency * обязательный
string Валюта в ISO-4217 формате, например USD
plan object Секция параметров плана.
amount * обязательный
integer Стоимость плана в минимальных единицах.
interval integer Длительность плана (целое число)
interval_unit string Единица изменения интервала (hour - час, day - день или month - месяц)
trial object
amount integer Стоимость пробного периода в минимальных единицах. Работает только с trial.interval
interval integer Длительность пробного периода (целое число). Работает только с trial.amount
interval_unit string Единица измерения интервала пробного периода (hour - час, day - день или month - месяц)
as_first_payment boolean true или false. Если значение true, система считает платеж за пробный период первым платежом, что позволяет использовать все правила списания средств, в том числе и восcтановление после ошибок при оплате после пробного периода. Это повышает риск использования краденных и "одноразовых" карт для оплаты пробного периода. Если значение false, то при ошибке платежа, проведенного после окончания пробного периода, новые попытки списания средств проводиться не будут. По умолчанию false
language string Язык платежной страницы при оплате плана. По умолчанию - en. Доступные значения параметра language.
infinite boolean true или false. Значение true, если количество циклов оплаты бесконечно. По умолчанию true
billing_cycles integer Количество циклов оплаты. Параметр игнорируется если infinite true
number_payment_attempts integer Количество неудачных попыток оплаты, прежде чем отменить подписку. По умолчанию 3.

Если попытка возвращает статус failed, но ранее в рамках этой подписки были успешные транзакции, то система осуществит новую попытку списания на следующий день:

- в 03:00, если "prevent_payments_at_night":false,
- в 08:00, если "prevent_payments_at_night":true.

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

Если попытка снятия средств возвращает статус error, но ранее в рамках этой подписки были успешные транзакции, то повторная попытка списания будет осуществлена в начале следующего часа за исключением периода с 20:00 до 08:00, если "prevent_payments_at_night": true, до тех пор, пока попытка не завершится успешно или пока не закончится указанное количество попыток.
prevent_payments_at_night boolean true или false. При значении true, списание платежей по подписке будет производиться только в дневной период с 8.00 до 20.00 по времени системы. По умолчанию false.
Пример запроса на создание плана с бесконечным количеством циклов оплаты
curl https://api.unonapay.com/plans \
-X POST -u shop_id:secret_key \
-H "Content-Type: application/json" \
-d \
'
{
    "test": true,
    "title": "Basic plan",
    "currency": "USD",
    "plan": {
        "amount": 20,
        "interval": 20,
        "interval_unit": "day"
    },
    "trial": {
        "amount": 10,
        "interval": 10,
        "interval_unit": "hour"
    },
    "language": "ru",
    "infinite": true,
    "billing_cycles": null,
    "number_payment_attempts": 3
}
'
Пример запроса на создание плана с определённым количеством циклов оплаты
{
  "test": true,
  "title": "Basic plan",
  "currency": "USD",
  "plan": {
      "amount": 20,
      "interval": 20,
      "interval_unit": "day"
  },
  "trial": {
      "amount": 10,
      "interval": 10,
      "interval_unit": "hour"
  },
  "language": "en",
  "infinite": false,
  "billing_cycles": 12,
  "number_payment_attempts": 3
}
Ответ

Если права доступа и параметры верны, UnonaPay вернет 201 код состояния HTTP и данные нового плана. Иначе, система вернет 422 код состояния HTTP и сообщение об ошибке.

Пример ответа при успешном создании плана
{
    "id": "pln_a134847c902551de",
    "title": "Basic plan",
    "currency": "USD",
    "language": "ru"
    "plan": {
        "amount": 20,
        "interval": 20,
        "interval_unit": "day"
    },
    "trial": {
        "amount": 10,
        "interval": 10,
        "interval_unit": "hour"
    },
    "number_payment_attempts": 3,
    "test": true
}
Пример ответа на запрос на создание плана с неверными параметрами
{
    "errors": {
        "title": [
            "can't be blank"
        ]
    },
    "message": "Title can't be blank"
}

Получение ссылки на оплату

Для получения оплаты за план, направьте клиента через GET или POST запрос на https://api.unonapay.com/plans/{plan_id}/pay, где {plan_id} - это идентификатор плана.


Получение информации о плане

Для получения информации о плане отправьте GET запрос на https://api.unonapay.com/plans/{plan_id}, где {plan_id} - идентификатор плана.

Если такой план существует, система вернет вам 200 код состояния и полную информацию о нем.

Пример запроса на получение информации о плане с ID pln_a134847c902551de
curl -u shop_id:secret \
https://api.unonapay.com/plans/pln_a134847c902551de
Пример запроса на получение информации о плане
{
    "id": "pln_a134847c902551de",
    "title": "Basic plan",
    "currency": "USD",
    "language": "ru",
    "plan": {
        "amount": 20,
        "interval": 20,
        "interval_unit": "day"
    },
    "trial": {
        "amount": 10,
        "interval": 10,
        "interval_unit": "hour"
    },
    "number_payment_attempts": 3,
    "test": true
}

Получение информации о плане

Для запроса списка всех планов отправьте GET запрос на https://api.unonapay.com/plans.

Если планы имеются, UnonaPay вернет 200 код состояния и массив планов.

Пример запроса на список планов
curl -u shop_id:secret \
https://api.unonapay.com/plans
Пример ответа на запрос на список планов
[
    {
        "id": "pln_2b0c211f50deb72c",
        "title": "Basic plan",
        "currency": "USD",
        "language": "en",
        "plan": {
            "amount": 20,
            "interval": 7,
            "interval_unit": "day"
        },
        "trial": {
            "amount": 10,
            "interval": 40,
            "interval_unit": "hour"
        },
        "number_payment_attempts": 3,
        "test": true
    },
    {
        "id": "pln_75eca73bfdcf143a",
        "title": "Pro plan",
        "currency": "USD",
        "language": "fr",
        "plan": {
            "amount": 30,
            "interval": 7,
            "interval_unit": "day"
        },
        "trial": {
            "amount": 10,
            "interval": 40,
            "interval_unit": "hour"
        },
        "number_payment_attempts": 5,
        "test": true
    }
]