Рекарринг платежи / Оплата токеном

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

Рекарринг платежи это не автоматические платежи. Они все так же требуют подтверждения от пользователя. Если вам нужны автоматические платежи, то советуем использовать рекуррентные платежи.

Регистрация карты
Оплата токеном

Регистрация карты

Важно: Ранее в API использовалось поле cash_desk_uuid (UUID кассы).
Сейчас оно заменено на поле shop_uuid (UUID магазина).
Поле cash_desk_uuid считается устаревшим (deprecated) и не должно использоваться в новых интеграциях.
Если вы ранее отправляли cash_desk_uuid, обновите интеграцию и передавайте shop_uuid.

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

Получение токена происходит через вебхук (event card_token.create), поэтому вам важно правильно настроить вебхуки для этого функционала. Подробней о вебхуках можно прочитать в разделе Вебхуки.

Так же можно получить uuid токена (registered_token_uuid) через получение информации о заказе по UUID заказа, который был создан при регистрации карты.

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


POST https://api.capitalpay.biz/api/public/order/register
 
Content-Type: application/json
Accept: application/json
Signature: {generated_hmac_signature}
 
{
  "shop_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"
}

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

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

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

external_client_id
external_data
external_order_id


{external_client_id};{external_data};{external_order_id};
123456;{"key": "value"};123456;

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

В ответе вы получите 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",
      "shop_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",
    }
  }
}

Webhook events

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

order.create
order.status.update
card_token.create

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

Оплата токеном

После успешной регистрации карты, вы получите UUID токен, который можно использовать для последующих платежей. Логика запроса аналогична созданию платежной ссылки, но к запросу требуется добавить поле token_uuid с полученным UUID токена. В ответ вы получите URL для перехода на страницу оплаты, а также информацию о заказе. Клиента нужно перенаправить на этот URL для возможного прохождения 3d secure и завершения оплаты. По окончанию клиент будет перенаправлен на success_url, а в случае ошибки - на fail_url. В случае отсутствия этих параметров клиента перенаправит на нашу страницу с результатом оплаты.