Сценарий оплаты по подписке
Сценарий работы с подписками - планы, пробные периоды, рекуррентные списания и callback по продлениям.
Подписки позволяют автоматически списывать оплату с покупателя с заданным периодом (например, ежемесячный доступ к сервису). АТОЛ Pay сам инициирует рекуррентные списания и уведомляет вас callback-ами о каждом продлении.
Пошаговый сценарий
Клиент выбирает подписку на сайте или в приложении продавца (например, ежемесячный доступ к услуге).
Продавец создает план подписки -
POST /v1/ecom/subscription-plans
(название, период, пробный период, сумма, returnUrl, данные для чека).
АТОЛ Pay возвращает идентификатор плана (id).
План можно создать один раз и переиспользовать для всех клиентов.
Продавец создает подписку для клиента -
POST /v1/ecom/buyer-subscriptions/order,
указав subscriptionPlanId (или externalPlanId, или полные данные плана в
subscriptionPlan) и данные покупателя (buyer).
АТОЛ Pay возвращает subscriptionId и paymentUrls.main - ссылку на оплату
первого платежа.
Клиент на платежной странице вводит данные карты (для подписок доступна только оплата картой) и подтверждает оплату. При необходимости проходит 3-D Secure.
При успешной оплате АТОЛ Pay активирует подписку и отправляет callback:
type: "subscription", status: "success", subscriptionStatus: "new"
(или "trial", если начался пробный период).
Если платеж не удался (status: "fail", subscriptionStatus: "retry") -
уведомите клиента о проблеме.
Для последующих платежей АТОЛ Pay автоматически инициирует списание в
соответствии с периодом подписки и отправляет callback с
subscriptionStatus: "prolongation" (успех) или "retry" (ошибка, будет
повторная попытка).
Продавец может отменить подписку -
POST /v1/ecom/buyer-subscriptions/{subscriptionId}/cancel.
АТОЛ Pay подтверждает отмену callback-ом с subscriptionStatus: "canceled".
Sequence-диаграмма
Жизненный цикл подписки
new или trial -> prolongation -> prolongation -> ... -> retry -> ... -> retry -> canceledsubscriptionStatus | Значение |
|---|---|
new | Оформлена новая подписка |
trial | Оформлен пробный период |
prolongation | Подписка продлена |
retry | Продление неуспешно, была попытка оплаты (передается retryNum) |
error | Попытки закончились (статус зарезервирован на будущее) |
canceled | Подписка отменена мерчантом/клиентом или автоматически после исчерпания попыток |
paused | Подписка приостановлена (статус зарезервирован на будущее) |
Пробный период
Пробный период (trialPeriod) задается в плане подписки. Если при создании
заказа передан buyer.id, использование пробного периода определяется по
нему: клиент, уже использовавший пробный период, для следующей подписки его
не получит.
Периоды в минутах и секундах доступны только на тестовых средах - они удобны для отладки рекуррентных списаний без ожидания суток.