Рекуррентные платежи / Подписка

Рекуррентные платежи (или подписка) позволяют клиенту совершать регулярные периодические платежи за товары или услуги. Это может быть полезно для сервисов с периодической оплатой, таких как подписки на контент, услуги или товары. Основное отличие от обычных платежей в том, что при создании рекуррентного платежа вы указываете частоту платежей, например, еженедельно, ежемесячно и т.д. При этом клиент вводит платежные данные только один раз, и дальше на своей стороне мы будем автоматически создавать и проводить новые платежи в соответствии с заданной частотой.

Важно! В тестовой среде рекуррентные платежи работают с сокращенными периодами. Например, если вы указали частоту weekly, то в тестовой среде платежи будут проводиться каждые 5 минут.

Таблица с частотами рекуррентных платежей:

Также в тестовой среде осуществляется только 10 рекуррентных платежей, после чего выдаст ошибку Limit Exceeded.

• Создание платежной ссылки для рекуррентных платежей / подписок
  • Пример запроса
  • Пример ответа
  • Создание подписи
  • Поля запроса
  • Webhook events
• Остановка цепочки рекуррентных платежей / Отмена подписки
  • Пример запроса
  • Пример ответа
  • Создание подписи
• Перезапуск цепочки рекуррентных платежей
  • Пример запроса
  • Создание подписи

Создание платежной ссылки для рекуррентных платежей / подписок

Пример запроса

POST https://api.capitalpay.biz/api/public/order/recurrent
 
Content-Type: application/json
Accept: application/json
Signature: {generated_hmac_signature}
 
{
  "amount": 100.50,
  "currency_code": "KZT",
  "cash_desk_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Order Title",
  "description": "Order Description",
  "external_client_id": 123456,
  "external_data": "{\"key\": \"value\"}",
  "external_order_id": 123456,
  "locale": "ru|en",
  "fail_url": "https://example.com/fail",
  "success_url": "https://example.com/success",
  "webhook_url": "https://example.com/webhook",
  "recur_frequency": "weekly|monthly|quarterly|yearly"
}

Создание подписи для рекуррентного платежа

Особенности формирования подписи в заголовке можно посмотреть в разделе Создание подписи

Для формирования подписи используются следующие поля в указанном порядке:

• amount
• currency_code
• external_client_id
• external_data
• external_order_id
• recur_frequency

{amount};{currency_code};{external_client_id};{external_data};{external_order_id};{recur_frequency};
100.50;KZT;123456;{"key": "value"};123456;weekly;

Пример ответа

В ответе вы получите URL для перехода на страницу оплаты, а также информацию о заказе.

HTTP/1.1 200 OK
{
  "status": true,
  "data": {
    "url": "https://platform.capitalpay.biz/order/123e4567-e89b-12d3-a456-426614174000",
    "order": {
      "id": 123456,
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "cash_desk_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "external_order_id": 123456,
      "external_client_id": 123456,
      "external_data": "{\"key\": \"value\"}",
      "status_id": 1,
      "status": "Created",
      "error_code": null,
      "error_message": null,
      "payment_method_id": 1,
      "recur_frequency": "weekly",
      "recur_status": "created",
      "recur_expired_at": null,
      "amount": 100.50,
      "currency_id": 1,
      "currency": "KZT",
      "title": "Order Title",
      "description": "Order Description",
      "refund_amount": null,
      "refund_description": null,
      "webhook_url": "https://example.com/webhook",
      "success_url": "https://example.com/success",
      "fail_url": "https://example.com/fail",
      "locale": "ru",
      "transaction_end_at": null,
      "is_test": false,
      "created_at": "2023-10-01T12:00:00Z",
    }
  }
}

Поля запроса

external_order_id, external_client_id и external_data поля для внешнего идентификатора заказа и клиента. Они могут быть использованы для связывания платежного API с внешней системой мерчанта. Эти поля не обязательны, но могут быть полезны при интеграции с системой мерчанта.

Webhook events

При создании рекуррентного платежа вы можете указать URL для вебхука (webhook_url), на который будут отправляться следующие события:

• order.create
• order.status.update
• subscription.create
• subscription.status.update

Детальней о вебхуках можно прочитать в разделе Вебхуки.

Остановка цепочки рекуррентных платежей / Отмена подписки

В случае если клиент хочет остановить цепочку рекуррентных платежей или отменить подписку, необходимо отправить запрос на отмену рекуррентного платежа. При этом подписка перейдет в статус Canceled, и в дальнейшем, по ней больше не будет проводиться платежи. Из статуса Canceled подписку нельзя возобновить.

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

Пример запроса

DELETE https://api.capitalpay.biz/api/public/order/recurrent/{uuid}
Content-Type: application/json
Accept: application/json
Signature: {generated_hmac_signature}

Пример ответа

HTTP/1.1 200 OK
{
  "status": true,
  "data": {
    "id": 123456,
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "cash_desk_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "external_order_id": 123456,
    "external_client_id": 123456,
    "external_data": "{\"key\": \"value\"}",
    "status_id": 1,
    "status": "Created",
    "error_code": null,
    "error_message": null,
    "payment_method_id": 1,
    "recur_frequency": "weekly",
    "recur_status": "cancelled",
    "recur_expired_at": "2030-12-30",
    "amount": 100.50,
    "currency_id": 1,
    "currency": "KZT",
    "title": "Order Title",
    "description": "Order Description",
    "refund_amount": null,
    "refund_description": null,
    "webhook_url": "https://example.com/webhook",
    "success_url": "https://example.com/success",
    "fail_url": "https://example.com/fail",
    "locale": "ru",
    "transaction_end_at": null,
    "is_test": false,
    "created_at": "2023-10-01T12:00:00Z",
  }
}

Создание подписи для отмены

Подпись создается с помощью HMAC SHA256. Для создания подписи необходимо использовать следующие поля в заданном порядке:

• uuid

Пример строки для подписи:

{uuid};
123e4567-e89b-12d3-a456-426614174000;

Перезапуск цепочки рекуррентных платежей

Если при автоматической попытке провести рекуррентный платеж возникла ошибка (у клиента недостаточно средств на карте, банк не доступен и т.д.), тогда подписка по этим платежам переходит в статус Failed. Вы можете вручную перезапустить цепочку рекуррентных платежей, после устранения проблемы (например, клиент пополнил баланс карты).

В случае успешного проведения платежа, подписка перейдет в статус Active, и дальнейшие платежи будут проводиться в соответствии с заданной частотой на основе новой даты успешного платежа.

Пример запроса

POST https://api.capitalpay.biz/api/public/order/recurrent/{uuid}/restart
Content-Type: application/json
Accept: application/json
Signature: {generated_hmac_signature}

Создание подписи для перезапуска

Подпись создается с помощью HMAC SHA256. Для создания подписи необходимо использовать следующие поля в заданном порядке:

• uuid

Пример строки для подписи:

{uuid};
123e4567-e89b-12d3-a456-426614174000;