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

Токенизация

Транзакция используется для токенизации банковской карты покупателя и проведения 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 транзакцию.
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 цифр номера карты.
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 Секция с данными о прохождении проверок транзакции сервисом Умная Маршрутизация.
data object Секция с данными о проверке транзакции правилами сервиса Умная Маршрутизация.
matched_actions object Секция со списком действий, которые были применены к транзакции.
skip_3ds array Действие, означающее, что проверка 3-D Secure для транзакции была пропущена; массив правил, в результате которого(-ых) было применено действие. Каждое правило представляет собой секцию со следующими параметрами:

alias - имя правила;
description - описание правила;
account - учетная запись, для которой было создано правило. Уточните у вашего менеджера, доступна ли для вашего магазина опция Skip 3-D Secure.
force_3ds array Действие, означающее, что к транзакции была применена проверка 3D Secure; массив правил, в результате которого(-ых) было применено действие. Каждое правило представляет собой секцию со следующими параметрами:

alias - имя правила;
description - описание правила;
account - учетная запись, для которой было создано правило.
Пример ответа 
{
  "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
    }
  }
}
Пример ответа в случае, если к транзакции было применено действие Skip 3ds по результатам прохождения правила Умной Маршрутизации 
{
  "transaction": {
    "uid": "087b516e-fe96-4571-8b81-09b4055b2197",
    "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-03-27T08:12:45.947Z",
    "updated_at": "2024-03-27T08:12:47.454Z",
    "paid_at": null,
    "language": "en",
    "redirect_url": "https://processing.ecomcharge.com/process/087b516e-fe96-4571-8b81-09b4055b2197",
    "status_code": null,
    "id": "087b516e-fe96-4571-8b81-09b4055b2197",
    "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": "507cd554-d400-455e-b3c2-cba6dc032636"
    },
    "additional_data": {
      "contract": [
        "recurring"
      ]
    },
    "smart_routing_verification": {
      "status": "successful",
      "data": {
        "skip_3ds": true,
        "status": "passed",
        "object": "3483",
        "object_name": "gw_3483",
        "object_flows": [],
        "object_defined_via": "allowed objects",
        "action_rules": {
          "Shop_1673_Good Point 2": {
            "skip 3 ds": {
              "skip 3 ds": "skip_3ds"
            }
          }
        },
        "matched_actions": {
          "skip_3ds": [
            {
              "alias": "skip 3 ds",
              "description": "skip 3 ds",
              "account": "Shop_1673_Good Point 2"
            }
          ]
        },
        "wb_lists": {
          "psp_black_list": "not_matched",
          "psp_white_list": "not_matched"
        }
      }
    },
    "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
    }
  }
}