Токенизация
Транзакция используется для токенизации банковской карты покупателя и проведения 3-D Secure проверки.
Списания средств с карты не происходит. Используйте полученный токен, чтобы провести оплату или авторизацию.
Запрос
Отправьте POST
запрос на https://processing.ecomcharge.com/transactions/tokenizations
со следующими параметрами:
Параметр | Тип | Описание |
---|---|---|
amount * обязательный |
bigInteger | Стоимость в минимальных денежных единицах. Например, $32.45 должна быть отправлена как 3245 . |
currency * обязательный |
string | Валюта в ISO-4217 формате, например, USD . |
description * обязательный |
string (255) | Описание заказа. |
tracking_id | string (255) | ID транзакции или заказа в вашей системе. Пожалуйста, используйте уникальное значение для того, чтобы при запросе статуса транзакции получить актуальную информацию. В противном случае вы получите первую найденную по tracking_id транзакцию. В параметре может быть отправлено несколько значений, разделенных символом ; . Например: "cbe59142-90af-4aea-b5a5-5bf3f66cf3da;f7883cb9-0e26-43a7-beb7-4027cb55d1a6;4a6a89d5-6950-400f" . Если в запросе было передано более одного значения tracking_id , поиск транзакции в личном кабинете может быть осуществлен по любому из них. |
duplicate_check | boolean | Параметр управляет процессом проверки входящего запроса на уникальность. Если true , то повторный запрос на токенизацию с таким же amount и number , отправленный в течение 30 секунд после первого запроса, будет отклонен. По умолчанию, этот параметр имеет значение true . |
dynamic_billing_descriptor | string | Динамический идентификатор платежа. |
language | string | Язык вашей страницы оформления заказа. Если параметр установлен и email уведомления о транзакции включены, то eComCharge отправит email, язык текста которого будет language . По умолчанию - en . Доступные значения параметра language . |
notification_url | string | URL, на который будут приходить уведомления. Формат запроса уведомления аналогичен формату ответа транзакции. |
verification_url | string | URL, на который будут приходить запрос на подтверждение транзакции. Формат запроса на подтверждение аналогичен формату ответа транзакции. |
return_url * условно обязательный |
string | URL на стороне торговца, на который eComCharge будет перенаправлять покупателя после возврата с 3-D Secure проверки. Параметр обязателен, если 3-D Secure включен. Обратитесь к менеджеру за информацией. |
test | boolean | Транзакция будет тестовой, если значение true . |
credit_card | object | |
number * обязательный |
string | Номер карты, длина - от 12 до 19 цифр. |
verification_value * условно обязательный |
string | 3-х или 4-х цифровой код безопасности (CVC2, CVV2 или CID, в зависимости от бренда карты). Обязательность параметра зависит от требований эквайера и настроек магазина. |
holder * условно обязательный |
string (35) | Имя владельца карты. Максимальная длина: 35 символов. Параметр опционален в системе eComCharge, но может требоваться банком-эквайером. |
exp_month * обязательный |
string (2) | Месяц окончания срока действия карты, представленный одной или двумя цифрами (например, 01). |
exp_year * обязательный |
string (4) | Год окончания срока действия карты, представленный четырьмя цифрами (например, 2026). |
skip_three_d_secure_verification | boolean | Параметр используется, если вы хотите, чтобы покупатель не проходил авторизацию по протоколу 3-D Secure. Уточните у службы технической поддержки, можете ли вы использовать этот параметр. Если значение параметра - true , eComCharge не применяет 3-D Secure проверку к транзакции токенизации. По умолчанию, установлено значение false .Параметр force_three_d_secure_verification имеет больший приоритет, чем параметр skip_three_d_secure_verification , когда оба переданы со значением true .Значение игнорируется, если к транзакции применено правило Умной Маршрутизации с действием Force 3ds или Skip 3ds . |
force_three_d_secure_verification | boolean | Параметр используется, если вы хотите, чтобы покупатель проходил авторизацию по протоколу 3-D Secure. Уточните у службы технической поддержки, можете ли вы использовать этот параметр. Если значение параметра - true , eComCharge принудительно применяет 3-D Secure проверку к транзакции токенизации. По умолчанию, установлено значение false .Параметр force_three_d_secure_verification имеет больший приоритет, чем параметр skip_three_d_secure_verification , когда оба переданы со значением true .Значение игнорируется, если к транзакции применено правило Умной Маршрутизации с действием Force 3ds или Skip 3ds . |
three_d_secure | object | Секция для настройки схемы обработки транзакций с проверкой 3-D Secure 2.0 с расширенным контролем. |
advanced | boolean | Установите значение true , чтобы обрабатывать платежи по схеме с расширенным контролем. В противном случае установите false . |
additional_data | object | Секция, содержащая дополнительную информацию о платеже. |
receipt_text | array | Текст, который будет добавлен в письмо покупателю. Должен быть представлен как массив строк, например, ["Первая строка", "Вторая строка"] . |
contract | array | Массив, элементами которого могут быть параметры:recurring - eComCharge вернет токен карты для осуществления последующих платежей без повторного ввода реквизитов карты. Покупатель, соглашаясь с условиями регулярного списания, единожды производит оплату, вводя реквизиты карты, включая проверочный код карты CVC/CVV и проходя авторизацию по протоколу 3-D Secure;oneclick - eComCharge вернет токен карты для осуществления последующих платежей по схеме oneclick, когда на странице оплаты будут уже частично заполнены реквизиты карты, а покупателю для завершения оплаты достаточно ввести проверочный код карты CVC/CVV и пройти авторизацию по протоколу 3-D Secure;credit - eComCharge вернет токен карты для осуществления транзакций выплаты средств. |
customer * условно обязательный |
object | Секция информации о покупателе. Уточните у службы технической поддержки, необходимо ли передавать параметры данной секции. |
ip * условно обязательный |
string | IP-адрес покупателя. |
email * условно обязательный |
string | email покупателя. |
device_id * условно обязательный |
string | ID устройства покупателя. |
birth_date * условно обязательный |
string | Дата рождения покупателя в формате ISO 8601 (YYYY-MM-DD ). |
billing_address | object | Узнайте у службы поддержки, должны ли вы отправлять эти данные. |
first_name * условно обязательный |
string (30) | Имя покупателя. |
last_name * условно обязательный |
string (30) | Фамилия покупателя. |
country * условно обязательный |
string | Страна покупателя в формате ISO 3166-1 alpha-2. |
city * условно обязательный |
string (60) | Город покупателя. |
state * условно обязательный |
string | Двухбуквенная аббревиатура штата, если страна покупателя US или CA . |
zip * условно обязательный |
string | (необязательный) почтовый индекс покупателя. Для country=US , формат почтового индекса должен иметь вид NNNNN или NNNNN-NNNN. |
address * условно обязательный |
string (255) | Адрес покупателя. |
phone * условно обязательный |
string (100) | Номер телефона покупателя. |
travel | object | Секция, предоставляющая расширенную информацию о продаже авиабилетов, туристических путевок и т.д. |
airline | object | Необязательная секция, содержащая расширенную информацию о проданном авиабилете. |
agency_code | string | IATA код агентства, например, 03 . |
agency_name | string | Название агентства, продавшего билет, например, Coral travel . |
ticket_number | string | 14-значный номер билета. Должен содержать 3-значный код билета, 4-значный номер формы, 6-значный серийный номер и контрольное число, например, 390 5241 025377 1 . |
booking_number | string | Код брони, например, DKZVUA . |
restricted_ticked_indicator | string | Если билет можно вернуть - 0 . Если вернуть нельзя - 1 . |
legs | array | Список перелетов, каждый элемент которого состоит из: |
airline_code | string | 2-символьный IATA код авиакомпании, например, B2 . |
stop_over_code | string | IATA код длительности пересадки. Если пересадка больше 24 часов, то значение параметра O или пусто. Если аэропорт является транзитным, то значение параметра X . |
flight_number | string | Номер рейса, например, A3 971 . |
departure_date_time | string | Время и дата вылета, например, 2014-05-26T05:15:00 . |
arrival_date_time | string | Время и дата прибытия, например, 2014-05-26T07:30:00 . |
originating_country | string | Страна вылета, например, RU . |
originating_city | string | Город вылета, например, Moscow . |
originating_airport_code | string | 3-значный код аэропорта вылета, например, DME . |
destination_country | string | Страна прилета, например, Greece . |
destination_city | string | Город прилета, например, Athens . |
destination_airport_code | string | 3-значный код аэропорта прилета, например, ATH . |
coupon | string | Номер скидочного купона, если был применен. |
class | string | Класс полета, 1-значный IATA код, например, C . |
passengers | array | Список пассажиров, каждый элемент которого состоит из: |
first_name | string | Имя пассажира, например, KONSTANTIN . |
last_name | string | Фамилия пассажира, например, IVANOV . |
Пример запроса
{
"request":{
"amount":100,
"currency":"USD",
"description":"Test transaction",
"tracking_id":"your_uniq_number",
"language":"en",
"billing_address":{
"first_name":"John",
"last_name":"Doe",
"country":"US",
"city":"Denver",
"state":"CO",
"zip":"96002",
"address":"1st Street"
},
"credit_card":{
"number":"4200000000000000",
"verification_value":"123",
"holder":"John Doe",
"exp_month":"05",
"exp_year":"2026"
},
"customer":{
"ip":"127.0.0.1",
"email":"john@example.com"
}
}
}
Ответ
Ответ будет содержать те же параметры, что и запрос, а также дополнительные параметры:
Параметр | Тип | Описание |
---|---|---|
transaction | object | |
uid * обязательный |
string | UID обработанной транзакции. |
status * обязательный |
string | Статус обработанной транзакции. |
message * обязательный |
string | Сообщение с результатом запроса. |
tracking_id * обязательный |
string | Значение параметра tracking_id из запроса. |
language * обязательный |
string | Значение параметра language из запроса или en , если параметр не был передан. |
type * обязательный |
string | Тип транзакции. |
payment_method_type * обязательный |
string | Способ оплаты, используется для завершения транзакции: credit_card . |
credit_card | object | |
brand * обязательный |
string | Определенный бренд карты. |
product * обязательный |
string | Код типа карточного продукта. |
last_4 * обязательный |
string | Последние 4 цифры карты. |
first_1 * обязательный |
string | Первая цифра карты. |
bin * обязательный |
string (6) | Шестизначный банковский идентификационный номер. Первые 6 цифр номера карты. |
bin_8 * обязательный |
string (8) | Восьмизначный банковский идентификационный номер. Первые 8 цифр номера карты. Значение возвращается для карт Visa, Mastercard, Maestro и соответствующих кобрендинговых карт. Для брендов других платежных карт значение параметра – null . |
issuer_country * обязательный |
string (2) | Страна банка, выпустившего карту в формате ISO 3166-1 alpha-2. |
issuer_name * обязательный |
string | Название банка, выпустившего карту. |
stamp * обязательный |
string | Хэш карты. Постоянная величина, даже если дата окончания действия карты или владелец изменены. |
token * required |
string | Токен банковской карты. Сохраните токен и принимайте повторные платежи от покупателя без использования данных карточки покупателя. Токен позволяет вам сохранить данные покупателя, необходимые для осуществления платежа и использовать их при совершении ими новых покупок или продления услуг вашего магазина. |
three_d_secure_verification | object | Блок с результатом проверки 3-D Secure. |
tokenization | object | |
message * обязательный |
string | Сообщение о результате токенизации. |
status * обязательный |
string | Статус токенизации. Допустимые значения: successful , failed . |
additional_data | object | Секция, содержащая дополнительную информацию о платеже. |
receipt_text | array | Текст, который будет добавлен в письмо покупателю. |
smart_routing_verification | object | Секция с данными о прохождении проверок транзакции сервисом Умная Маршрутизация. |
status | string | Статус обработки транзакции сервисом Smart Routing. |
Пример ответа
{
"transaction": {
"uid": "e89abc1a-1d18-4d0f-83a1-7009b333dce0",
"status": "successful",
"amount": 492,
"currency": "EUR",
"description": "Test transaction",
"type": "tokenization",
"payment_method_type": "credit_card",
"tracking_id": "your_uniq_number",
"message": "Successfully processed",
"test": true,
"created_at": "2024-04-02T14:32:33.946Z",
"updated_at": "2024-04-02T14:32:35.000Z",
"paid_at": null,
"language": "en",
"redirect_url": "https://processing.ecomcharge.com/process/e89abc1a-1d18-4d0f-83a1-7009b333dce0",
"status_code": null,
"id": "e89abc1a-1d18-4d0f-83a1-7009b333dce0",
"credit_card": {
"holder": "John Doe",
"stamp": "bb58cad9c1204ca2287b3e1006cc1a2c0fb8f062dde9e5232c8be5498bd0e62a",
"brand": "visa",
"last_4": "1097",
"first_1": "4",
"bin": "401200",
"bin_8": "40120000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 7,
"exp_year": 2026,
"token_provider": null,
"token": "e3ba5977-8705-4496-bf90-a6a93d3d31cc"
},
"additional_data": {
"contract": [
"recurring"
]
},
"smart_routing_verification": {
"status": "successful"
},
"tokenization": {
"message": null,
"gateway_id": 3483,
"status": "successful"
},
"customer": {
"ip": null,
"email": null,
"device_id": null,
"birth_date": null
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": null
}
}
}