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

Платежи по сохранённым данным карты

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

Как это работает

Привязка карт подразумевает следующие этапы:

  • инициализирующая транзакция, во время которой покупатель указывает данные своей карты и даёт согласие на их сохранение для последующих списаний. Во время этой транзакции может быть выполнена проверка 3-D Secure;
  • получение токена карты в ответе на транзакцию или в автоматическом уведомлении, а также сохранение полученного токена в системе торговца;
  • последующие транзакции по токену карты без необходимости участия покупателя.

Описанная схема подходит для следующих сценариев:

  • для нерегулярных списаний по запросу;
  • для регулярных платежей.

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

Info

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

1) Инициализирующая транзакция

Отправьте один из поддерживаемых запросов в зависимости от типа интеграции, указав recurring и card_on_file в качестве значения additional_data.contract.

Если эквайер поддерживает транзакции с нулевой суммой, рекомендуется использовать тип транзакции authorization с нулевой суммой ("amount": 0).

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

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

Интеграция через виджет

  • Настройте интеграцию с виджетом;
  • отправьте запрос на создание токена платежа;
    • в качестве transaction_type укажите payment, authorization или tokenization;
    • если вы используете tokenization в качестве transaction_type, вы можете указать любую сумму в параметре amount;
    • для типов транзакции payment и authorization укажите recurring и card_on_file в качестве значения checkout.order.additional_data.contract;
  • используйте полученный токен платежа для интеграции виджета.

Интеграция через платежную страницу

  • Отправьте запрос на создание токена платежа.
    • в качестве transaction_type укажите payment, authorization или tokenization;
    • если вы используете tokenization в качестве transaction_type, вы можете указать любую сумму в параметре amount;
    • для типов транзакции payment и authorization укажите recurring и card_on_file в качестве значения checkout.order.additional_data.contract;
  • перенаправьте покупателя на redirect_url из ответа для завершения оплаты.

Warning

Обратите внимание, что при использовании транзакции токенизации в качестве инициализирующей, последующую транзакцию необходимо совершить в течение часа. В противном случае потребуется повторная проверка 3-D Secure с участием покупателя.

Warning

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

Пример инициализирующей транзакции: создание токена платежа 
{
  "checkout": {
    "test": true,
    "transaction_type": "payment",
    "attempts": 3,
    "settings": {
      "return_url": "https://example.com/return",
      "notification_url": "https://example.com/notification",
      "language": "en"
    },
    "payment_method": {
      "types": [
        "credit_card"
      ]
    },
    "order": {
      "currency": "USD",
      "amount": 100,
      "description": "Test transaction",
      "tracking_id": "abc-12345",
      "additional_data": {
        "contract": [
          "recurring",
          "card_on_file"
        ]
      }
    },
    "customer": {
      "address": "Baker street 221b",
      "country": "GB",
      "city": "London",
      "email": "jake@example.com"
    }
  }
}
Пример инициализирующей транзакции при использовании API для платежей картами: оплата/авторизация 
{
    "request": {
        "amount": 100,
        "currency": "USD",
        "description": "Test transaction", 
        "tracking_id": "tracking_id_1", 
        "language": "en",     
        "credit_card": { 
            "number": "4200000000000000",
            "verification_value": "123",
            "holder": "John Doe",
            "exp_month": "05",
            "exp_year": "2030"
        },       
        "additional_data": {
            "contract": [ 
                "recurring",
                "card_on_file"
            ]
        }
    }
}

2) Сохранение токена карты

После успешной инициализирующей транзакции токен карты будет отправлен:

  • в параметре credit_card.token в автоматическом уведомлении после успешной оплаты/авторизации/токенизации;
  • в параметре credit_card.token в синхронном ответе на запросы авторизации, оплаты или токенизации.

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

В синхронном ответе и автоматическом уведомлении в параметре credit_card.last_4 также будут отправлены 4 последние цифры номера карты покупателя. Это значение можно использовать, чтобы отображать в личном кабинете пользователя сохранённую карту в формате ХХХХ 1234.

Пример автоматического уведомления с токеном карты в параметре credit_card.token 
{
  "transaction": {
    "uid": "4a3365f7-b4ef-4fa7-9b21-bd552e8c8d6e",
    "status": "successful",
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction",
    "type": "payment",
    "payment_method_type": "credit_card",
    "tracking_id": "abc-12345",
    "message": "Transaction is successful.",
    "test": true,
    "created_at": "2025-07-15T10:56:27.137Z",
    "updated_at": "2025-07-15T10:56:32.458Z",
    "paid_at": "2025-07-15T10:56:32.385Z",
    "expired_at": null,
    "recurring_type": "initial",
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "credit_card": {
      "holder": "Jake Doe",
      "stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
      "brand": "visa",
      "last_4": "0000",
      "first_1": "4",
      "bin": "420000",
      "bin_8": "42000000",
      "issuer_country": "US",
      "issuer_name": "VISA Demo Bank",
      "product": "F",
      "exp_month": 9,
      "exp_year": 2027,
      "token_provider": null,
      "token": "2a4ef31c-bdc9-450b-a979-d533a19341ac"
    },
    "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/4a3365f7-b4ef-4fa7-9b21-bd552e8c8d6e/ca89173f01a8d828b90520ac06dd404031a820e1c4d3dbc1ecdb3aab7ccdf363?language=en",
    "status_code": null,
    "gateway": {
      "iframe": true
    },
    "mute_notifications": true,
    "version": 4,
    "psp_settled_at": null,
    "registry_id": null,
    "id": "4a3365f7-b4ef-4fa7-9b21-bd552e8c8d6e",
    "additional_data": {
      "contract": [
        "recurring",
        "card_on_file"
      ],
      "request_id": "50935403-5a18-4ecc-8f72-ece5a9eadf43",
      "vendor": {
        "name": "CTP",
        "token": "a0de2237fc2ba265b948073fdee6ebb8a8223cf1af951efdc09e8e369fd8efd5"
      }
    },
    "redirect_url": "https://demo-gateway.begateway.com/process/4a3365f7-b4ef-4fa7-9b21-bd552e8c8d6e",
    "code": "S.0000",
    "friendly_message": "The transaction is successfully processed.",
    "smart_routing_verification": {
      "status": "successful"
    },
    "payment": {
      "auth_code": "654321",
      "bank_code": "05",
      "rrn": "999",
      "ref_id": "777888",
      "message": "Payment was approved",
      "amount": 100,
      "currency": "USD",
      "billing_descriptor": "test descriptor",
      "gateway_id": 63498,
      "status": "successful"
    },
    "avs_cvc_verification": {
      "avs_verification": {
        "result_code": "A"
      },
      "cvc_verification": {
        "result_code": "1"
      }
    },
    "customer": {
      "ip": "37.214.28.71",
      "email": "jake@example.com",
      "device_id": "5766e9d0d09e0d0c00017b1ae78982a4",
      "birth_date": null,
      "external_id": null
    },
    "billing_address": {
      "first_name": "Jake",
      "last_name": "Doe",
      "address": "Baker street 221b",
      "country": "GB",
      "city": "London",
      "zip": null,
      "state": null,
      "phone": null
    }
  }
}

3) Последующие транзакции с применением токена карты

Для последующих списаний используйте сохранённый токен вместо данных карты в параметре request.credit_card.token. Для запроса на создание токена платежа, токен карты отправляется в параметре checkout.payment_method.credit_card.token.

Пример транзакции оплаты с использованием токена карты 
{
    "request": {
        "amount": 100,
        "currency": "USD",
        "description": "Test transaction",
        "notification_url": "https://example.com/notification",
        "tracking_id": "3567k7",
        "language": "en",
        "test": true,
        "credit_card": {
            "token": "2a4ef31c-bdc9-450b-a979-d533a19341ac"
        }
    }
}

Привязка карт