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

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

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

---

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

Запрос

Отправьте POST запрос на https://api.overpay.io/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.overpay.io/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
}

Ответ

Если права доступа и параметры верны, Overpay вернет 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.overpay.io/plans/{plan_id}/pay, где {plan_id} - это идентификатор плана.

---

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

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

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

Пример запроса на получение информации о плане с ID pln_a134847c902551de

curl -u shop_id:secret \
https://api.overpay.io/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.overpay.io/plans.

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

Пример запроса на список планов

curl -u shop_id:secret \
https://api.overpay.io/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
    }
]