Использование токенов

Токен (token) — уникальная, случайная последовательность из 64 символов, ассоциированная в Gate с определенной банковской картой и пользователем в подключенном проекте. Токен не содержит в себе конфиденциальной информации и может храниться в вашей системе, не вызывая угрозы нарушения стандартов безопасности по хранению данных по банковским картам.

Через Gate вы можете создавать токены автоматически или по запросу и производить оплаты и выплаты по имеющимся токенам.

Статусы токенов

Статус токена определяет возможность его использования для проведения оплат и выплат.

Табл. 1. Возможные статусы токенов
Статус Описание
active Действительный токен, по которому могут проводиться оплаты и выплаты
revoke Токен был отозван, проведение операций по токену невозможно
expiry Срок действия токена истек, проведение операций по токену невозможно

Автоматическая генерация токена

Автоматическая генерация токена происходит при проведении первой успешной оплаты или выплаты по банковской карте, а также при успешном холдировании средств.

Сгенерированный токен (token) и время его создания (token_created_at) возвращаются в оповещении о проведении платежа. Дополнительные сведения об оповещении см. в разделе Работа с оповещениями.

Notice: Для включения автоматической генерации токенов свяжитесь со службой технической поддержки support@ecommpay.com.

Генерация токена по запросу

Другим способом генерации токена является отправка запроса на генерацию токена. В запросе передаются данные, необходимые для генерации токена.

Сгенерированный токен и время его создания возвращаются в оповещении о генерации токена.

Создание запроса на генерацию токена

Прим.: Отправьте запрос /v2/customer/card/tokenize; метод отправки запроса — POST.

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

В оповещении вы получите токен банковской карты и время его создания. Подробнее см. в разделе Работа с оповещениями.

Рис. 1. Пример запроса на генерацию токена
{
    "customer": {
        "id": "1707",
        "ip_address": "1.87.128.111",
        "project_id": 11,
        "signature": "LLmhbDKdNhNLT+Qkr2SzbLbFYNxC9sZLnQKkrTFYNN06NMPmZS/BfWGucWQVZ2WM3v5N709w=="
    },
    "card": {
        "pan": "4314220000000056",
        "year": 2020,
        "month": 5,
        "card_holder": "PAUL SMITH"
    }
}

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

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

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

Дополнительные сведения об оплатах с использованием токена см. в Разовые оплаты.

Выплата по токену

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

Получение данных карты по токену

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

Прим.: Отправьте запрос /v2/customer/card/bytoken; метод отправки запроса — POST.

В запросе укажите идентификатор проекта, пользователя и токен.

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

Рис. 2. Пример запроса на получение данных карты по токену
{
	"customer": {
		"project_id": 12,
		"id":"test_customer",
		"signature":"2tlMuYxLW9Yu6RETr8pdCfmi0UPE8euD+BQjXWH6naCA9Ts6o4EVPjLyfbOQ+9ajAteg5lPk96Q=="
	},
	"token":"959c664ad64b8caa54bb7836ddc737fd1a3e6c7045679d71d89caff6c242a039"
}
Рис. 3. Пример оповещения с информацией о платежном инструменте
{
    "account": {
        "id": 2932,
        "number": "431422******0056",
        "type": "card",
        "additional": {
            "country": "GB",
            "phone": "4314220000000056",
            "email": "john@gmail.com",
            "card": {
                "expiry": "01/20",
                "holder": "JOHN JOHNSON",
                "type": "visa"
            }
          },
          "recurring_enable": false
        },
        "token": "959c664ad64b8caa54bb7836ddc777fd1a3e6c704b59bd71d89caff6c242a039"
    },
    "signature": "62kPxuCGqN4KDrxqqsuWnv0LOjdvUydWCxDmNPeq+AVW7/5UtLlmVL+SIyfbxot/Nf+47DEsAuW76DIgBg=="
}

Проверка карты по токену

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

Деактивация токена

Токен может быть деактивирован в Gate в одном из следующих случаев: вы деактивируете токен или у банковской карты заканчивается срок действия.

Вы можете, при необходимости, деактивировать токен из Gate, отправив запрос на деактивацию токена. Gate деактивирует токен.

Создание запроса на деактивацию токена

Прим.: Отправьте запрос /v2/customer/card/token/revoke; метод отправки запроса — POST.

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

После окончания обработки запроса вам придет оповещение с результатом деактивирования токена, включающий в том числе следующие параметры: project_id, token, status, и token_created_at.

Оповещение о создании или отключении токена

После выполнения запроса о создании или удалении токена, отправленного в конечную точку /v2/customer/card/tokenize, платежная платформа возвращает оповещение с информацией о результате выполнения запроса. В следующей таблице приведен набор параметров, который содержится в таком оповещении.
Табл. 2. Объекты и параметры оповещения о создании или удалении токена
Параметр Описание

general
object, required

 Объект с общими данными исходного запроса 1

project_id
string, required

 Уникальный идентификатор проекта 1-11

customer_id
string, optional

 Уникальный идентификатор пользователя в проекте 1-21

signature
string, required

 Подпись оповещения 1-31

request
object, required

 Объект с данными исходного запроса 2

id
integer, required

 Уникальный идентификатор запроса 2-12

action
string, optional

 Тип запроса. Возможны следующие варианты:
  • tokenize — запрос на создание токена;
  • token_revoke — запрос на отключение токена
  • параметр отсутствует — это означает, что токен деактивирован по истечению срока своего действия. Оповещение с отсутствующим параметром action инициируется в платежной платформе не по запросу, а автоматически, по истечении срока действия токена.
 2-22

status
string, required

 Статус запроса. Возможны следующие варианты:
  • success — запрос успешно выполнен;
  • error — во время выполнения запроса возникли ошибки. В этом случае в оповещение добавляется массив errors с подробной информацией об ошибках.
 2-32

errors
array, optional

 Массив объектов с информацией об ошибках. Присутствует в оповещении, только если в процессе обработки запроса возникли ошибки 2-42

ErrorItem
object, required

 Объект с информацией об одной отдельно взятой ошибке 2-4-12-4

code
string, optional

 Код ошибки 2-4-1-12-4-1

message
string, optional

 Сообщение, уточняющее причину ошибки 2-4-1-22-4-1

field
string, optional

Параметр исходного запроса, в котором допущена ошибка, если этот параметр удалось локализовать

 2-4-1-32-4-1

token
string, optional

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

token_created_at
string, optional

Дата и время генерации токена. Токен генерируется автоматически при успешной оплате, если подключена соответствующая функциональность.

Пример: 2017-07-21T03:31:24+0000

 4

token_status
string, optional

Статус токена.

Пример: active

 5
Рис. 4. Пример оповещения о генерации токена
{
"general":{
    "project_id":12,
    "customer_id":cust_123,
    "signature":"\/gmTHcy5wvrFD4ISuWEiV8+nOa3aqnLnyJ\/AupOYkl9S5eLJZ",
"request": {
			"id": "3c7f53fdbb5b8c96f9707457d75f",
			"action": "tokenize",
			"status": "success"
		},
"token":"2f0e75befacca30623354f9ffb0f44a80bee52982c39727b85039ef6f64309a1",
"token_created_at":"2017-11-28 13:30:57",
"token_status":"active"
}