Формирование токенов

Общая информация

При работе с Payment Page можно формировать токены, которые в дальнейшем хранятся на стороне веб-сервиса мерчанта и могут использоваться при проведении оплат через Payment Page и Gate, а также выплат через Gate.

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

Формирование токенов выполняется на основании данных платёжных карт пользователей (таких как номер карты, имя и фамилия её держателя и дата окончания срока действия этой карты) и возможно в следующих случаях:

  • при выполнении запроса на открытие Payment Page в режиме Card Tokenize;
  • при проведении первой успешной оплаты с сохранением платёжных данных карты в режиме Purchase, если такая настройка доступна для проекта мерчанта;
  • при проведении первой успешной оплаты или выплаты с использованием платёжной карты, если такая настройка доступна для проекта мерчанта.

По вопросам добавления возможности автоматической генерации токенов следует обращаться к специалистам технической поддержки — support@ecommpay.com.

В каждом из этих случаев для отдельной платёжной карты формируется один токен со сроком действия, соответствующим сроку действия этой карты, и этому токену присваивается статус active. При истечении срока действия токена этот статус изменяется на статус expiry, а при удалении токена по запросу со стороны веб-сервиса — на статус revoke. И в обоих случаях проведение платежей по этому токену становится недоступным.

Процедуры удаления токена, а также получения реквизитов платёжной карты по токену выполняются через интерфейс Gate и представлены в разделе Использование токенов.

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



В этом разделе представлена информация о формировании токенов с использованием Payment Page в режиме Card Tokenize. Информация о формировании токенов при проведении оплаты представлена в разделе Проведение оплат.

Схема работы

Для формирования токена через Payment Page со стороны веб-сервиса необходимо:

  1. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page.
  2. Принять оповещение о результате выполнения запроса со стороны платёжной платформы.

Формат запросов

Формат запроса на открытие Payment Page для формирования токена соответствует описанному в разделе Описание Payment Page API. При формировании такого запроса необходимо учитывать следующее:

  1. В запросе должны использоваться следующие обязательные параметры:
    • mode — индикатор режима работы Payment Page, для которого необходимо передавать значение card_tokenize.
    • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
    • customer_id — идентификатор пользователя в веб-сервисе мерчанта;
    • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
  2. Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр language_code — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически (по языку браузера, языку региона или по умолчанию; подробнее).
  3. Дополнительно в запросах могут использоваться любые другие параметры, используемые для работы Payment Page в режиме Card Tokenize. Полный список параметров вызова Payment Page представлен в разделе Параметры вызова платёжной формы.

Таким образом, корректный запрос на формирование токена должен содержать индикатор режима работы Payment Page, идентификатор проекта, подпись, а таже идентификатор пользователя.

{
   "mode": "card_tokenize",
   "project_id": 112,
   "customer_id": "cust_123",
   "signature": "TSzdE5rJZaA9VyJtnfRI362oGpfXriFf82MxF..."
}
Рис. 1. Пример запроса на открытие Payment Page
https://paymentpage.ecommpay.com/payment?signature=A%2Fqqxsl59tRrtACreixy8sieSfxR%2BC...&mode=card_tokenize&project_id=112&customer_id=cust_123&region_code=GB&language_code=en

Формат оповещений

Для оповещения о формировании токена используется стандартный формат, описание которого представлено в разделе Работа с оповещениями.

В следующем примере содержится информация о том, что в рамках проекта 112 для пользователя cust_123 сформирован токен (token). Также для этого токена указаны дата и время его создания (token_created_at) и текущий статус (token_status).

Рис. 2. Пример оповещения о формировании токена
{
    "general": {
        "project_id": 112,
        "customer_id": "cust_123",
        "signature": "mTHcy5wvpOYkl9S5eLJZ..."
    },
    "request": {
        "id": "3c7f53fdbb5b8c96f9707457d75f",
         "action": "tokenize",
         "status": "success"
     },
    "token":"2f0e75befacca30623354f9ffb0f44a80bee52982c39727b85039ef6f64309a1",
    "token_created_at":"2020-03-28 13:30:57",
    "token_status":"active"
}