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

Запрос на взимание платы

Банки-эквайеры могут применять различные сценарии и типы транзакций при проведении оплаты по сохраненным картам для вашей схемы расчета. Это означает, что вам необходимо было бы внедрять разные типы запросов при работе с несколькими эквайерами или при смене одного эквайера на другого.

eComCharge предлагает использовать единый запрос на взимание платы, который позволяет унифицировать процесс по привязке карт и списанию платы с них в дальнейшем.

Когда система eComCharge получает запрос на взимание платы, она автоматически преобразовывает такой запрос в платеж или авторизацию в зависимости от типа операции, поддерживаемого тем вашим эквайером, который будет обрабатывать транзакцию. Более того, если запрос на взимание платы был преобразован в запрос авторизации, система eComCharge самостоятельно отправит запрос на списание средств.

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

Запрос

Отправьте POST запрос на https://processing.ecomcharge.com/services/credit_cards/charges со следующими параметрами:

Параметр Тип Описание
amount * обязательный
integer Стоимость в минимальных денежных единицах (например, $32.45 должна быть отправлена как 3245).
currency * обязательный
string Валюта в формате ISO-4217 (например USD).
description * обязательный
string(255) Описание заказа.
tracking_id string(255) ID транзакции или заказа в вашей системе. Пожалуйста, используйте уникальное значение, чтобы получить актуальную информацию при запросе статуса транзакции. В противном случае вы получите информацию о первой найденной по tracking_id транзакции.
expired_at string Время в формате ISO 8601, до которого должна быть завершена операция. По умолчанию - бессрочно. Формат: YYYY-MM-DDThh:mm:ssTZD, где YYYY – год (например 2019), MM – месяц (например 02), DD – день (например 09), hh – часы (например 18), mm – минуты (например 20), ss – секунды (например 45), TZD – часовой пояс (+hh:mm или –hh:mm), например +03:00 для Минска. Если в указанный момент платёж всё ещё не будет оплачен, он будет переведён в статус expired.
duplicate_check boolean true или false. Параметр управляет процессом проверки входящего запроса на уникальность. По умолчанию этот параметр имеет значение true, поэтому, если в течение 30 секунд придет запрос на оплату с одинаковыми значениями amount и number или token, то запрос будет отклонен.
dynamic_billing_descriptor string Динамический идентификатор платежа.
language string Язык вашей страницы оформления заказа. Также является языком текста уведомления покупателя о транзакции по электронной почте, если оно настроено. По умолчанию - en. Доступные значения параметра language.
notification_url string URL, на который будут приходить уведомления. Формат запроса уведомления аналогичен формату ответа транзакции.
verification_url string URL, на который будет приходить запрос на подтверждение транзакции. Формат запроса на подтверждение аналогичен формату ответа транзакции.
return_url * условно обязательный
string URL на стороне торговца, на который eComCharge будет перенаправлять клиента после завершения 3-D Secure проверки. Параметр обязателен, если 3-D Secure включен. Обратитесь к менеджеру за дополнительной информацией.
test boolean true или false. Транзакция будет тестовой, если установлено значение true.
credit_card object Секция реквизитов карты.
number * обязательный
string Номер карты, длина - от 12 до 19 цифр.
verification_value string 3-х или 4-х цифровой код безопасности (CVC2, CVV2 или CID в зависимости от бренда карты). Может быть отправлен вместе с параметром token, и eComCharge передаст банку-эквайеру данные карты с CVC2/CVV2/CID.
holder * обязательный
string Имя держателя карты. Максимальная длина - 32 символа.
exp_month * обязательный
integer Месяц окончания срока действия карты, представленный двумя цифрами (например, 01).
exp_year * обязательный
integer Год срока окончания действия карты, представленный четырьмя цифрами (например, 2026).
token * условно обязательный
string Токен карты, полученный ранее. Обязателен, если не передаете реквизиты карты.
Если используется токен карты, то необходимо обязательно указывать параметр additional_data.contract.
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_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.
additional_data object Секция, содержащая дополнительную информацию о платеже. Уточните у службы поддержки, требуется ли вам передавать эти данные.
p2p object Секция для работы с AFT операциями.
service_id * условно обязательный
string Значение параметра уточните у вашего менеджера.
service_extension * условно обязательный
string Значение параметра уточните у вашего менеджера.
excluded_gateways array Массив для работы с каскадными платежами.
masterpass object Секция для работы с сервисом Masterpass.
params object Секция для параметров Masterpass.
session string ID пользовательской сессии.
receipt_text array Текст, который будет добавлен в письмо клиенту. Должен быть представлен как массив строк, например ["Первая строка", "Вторая строка"].
contract array Массив, элементами которого могут быть параметры:

recurring - eComCharge вернет токен карты для осуществления последующих платежей без повторного ввода реквизитов карты. Клиент указывает полные данные карты, включая проверочный код карты CVC/CVV, и проходит авторизацию по протоколу 3-D ­Secure только при проведении первоначального платежа;

oneclick - eComCharge вернет токен карты для осуществления последующих платежей по схеме oneclick, когда на странице оплаты будут уже частично заполнены реквизиты карты, а клиенту для завершения оплаты достаточно ввести проверочный код CVC/CVV и пройти авторизацию по протоколу 3-D ­Secure;

credit - eComCharge вернет токен карты для осуществления операций выплаты средств;

card_on_file - eComCharge вернет токен карты, чтобы сохранить его в учетной записи клиента на вашем сайте или в приложении и использовать этот токен для последующих платежей. Ознакомьтесь ниже с секцией card_on_file, чтобы узнать сценарии использования данного значения. Внимание! Опция card_on_file поддерживается не всеми эквайерами. Если вы хотите ее использовать, свяжитесь со своим аккаунт менеджером.
avs_cvc_verification object AVS/CVC проверка.
card_on_file object Секция атрибутов операции, которые будут отправлены в дальнейшем в платёжную систему. Если секция не передана, то для параметров initiator и type будут использованы значения по умолчанию.
initiator string Возможные значения:
merchant (по умолчанию) - операция инициирована вашей системой или приложением, от клиента не требуется дополнительных действий (например, автоматическое списание с карты клиента стоимости поездки в такси после ее завершения);

customer - операция инициирована клиентом, клиенту необходимо подтвердить проведение платежа (например, при размещении заказа клиент выбирает опцию оплаты сохраненной картой).
type string Используется, только если параметр additional_data.card_on_file.initiator имеет значение merchant.

delayed_charge (по умолчанию) - отложенная оплата (например, за оказанную услугу);

increment - досписание суммы (например, при допродаже товара или замене на более дорогой товар);

resubmission - повторная попытка списать деньги из-за предыдущего отказа в операции (например, не было денег на карте);

reauthorization - обновление авторизации (например, нужно повторно зарезервировать средства на карте в связи с истечением срока авторизации предыдущей операции);

no_show - проведение штрафного списания, если клиент не воспользовался услугой или товаром (например, не заехал в отель).
browser object Секция параметров браузера клиента. Параметры из секции передаются только при использовании протокола 3-D Secure 2.0.
accept_header integer Содержание HTTP-заголовка Accept запроса от браузера клиента.
screen_width integer Ширина экрана в пикселях. Соответствует параметру screen.width из JavaScript
screen_height integer Высота экрана в пикселях. Соответствует параметру screen.height из JavaScript
screen_color_depth integer Глубина цвета экрана в битах на пиксель. Соответствует параметру screen.colorDepth из JavaScript. Возможные значения:

1 - 1 bit
4 - 4 bits
8 - 8 bits
15 - 15 bits
16 - 16 bits
24 - 24 bits
32 - 32 bits
48 - 48 bits
window_width integer Размер окна браузера по горизонтали в пикселях. Соответствует параметру document.body.clientWidth из JavaScript.
window_height integer Размер окна браузера по вертикали в пикселях. Соответствует параметру document.body.clientHeight из JavaScript.
language string Язык навигатора. Соответствует параметру navigator.language из JavaScript.
java_enabled boolean Параметр показывает, включен ли java в текущем браузере или нет. Соответствует параметру navigator.javaEnabled() из JavaScript.
user_agent string Строка агента пользователя текущего браузера. Соответствует параметру navigator.userAgent из JavaScript.
time_zone integer Смещение часового пояса относительно часового пояса UTC в минутах для текущей локали. Соответствует параметру new Date().getTimezoneOffset() из JavaScript.
time_zone_name string Название часового пояса. Соответствует параметру Intl.DateTimeFormat().resolvedOptions().timeZone из JavaScript.
customer * условно обязательный
object Секция информации о покупателе.
Уточните у Службы технической поддержки, необходимо ли передавать параметры данной секции.
ip string IP-адрес клиента, производящего оплату на вашем сайте или в приложении.
email string Электронная почта клиента, производящего оплату на вашем сайте или в приложении.
device_id string ID устройства клиента, производящего оплату на вашем сайте или в приложении.
birth_date string Дата рождения клиента в формате ISO 8601 YYYY-MM-DD.
taxpayer_id string Идентификационный номер налогоплательщика (ИНН), присвоенный клиенту.
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 Почтовый индекс клиента. Если страна клиента - 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).

Ответ

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

Параметр Тип Описание
transaction object
type * обязательный
string Тип транзакции, имеет значение charge
parent_uid * обязательный
string ID транзакции списания средств, если общий запрос был преобразован в операции авторизации и списания. Совпадает со значением uid, если общий запрос был преобразован в операцию платежа.
redirect_url * обязательный
string URL страницы для завершения транзакции.

Если параметр status имеет значение incomplete, перенаправьте покупателя на этот URL для прохождения проверки 3-D Secure.

Info

В настоящий момент, если вы указываете charge как значение параметра transaction_type при использовании платежного виджета eComCharge, значения параметров rrn и bank_code в ответе на запрос могут отсутствовать.

Пример ответа на запрос на взимание платы
{
  "transaction": {
    "uid": "2-a658f32cfc",
    "parent_uid": "1-4ba3b43229",
    "status": "successful",
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction ütf",
    "type": "charge",
    "payment_method_type": "credit_card",
    "tracking_id": "tracking_id_000",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2021-12-22T10:20:26.768Z",
    "updated_at": "2021-12-22T10:20:26.810Z",
    "paid_at": "2021-12-22T10:20:26.802Z",
    "expired_at": null,
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "http://127.0.0.1:9887/process/2-a658f32cfc",
    "credit_card": {
      "holder": "John Doe",
      "stamp": "1cd7225cfc72c653c06bf40f7b7371d0a947ca8a37796b851e0aa4ece703b7c8",
      "brand": "mir",
      "last_4": "0013",
      "first_1": "2",
      "bin": "220138",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 12,
      "exp_year": 2026,
      "token_provider": null,
      "token": null
    },
    "receipt_url": "default_domain/customer/transactions/2-a658f32cfc/09418c951278567cba5060bfb9f6ea79a0ac255a5c47c2a2bbba8b2954ca62ba",
    "status_code": null,
    "id": "2-a658f32cfc",
    "additional_data": {
      "contract": ["card_on_file"]
    },
    "charge": {
      "message": "Capture was approved",
      "ref_id": "8889912",
      "rrn": null,
      "auth_code": null,
      "gateway_id": 1,
      "status": "successful"
    },
    "authorization": {
      "auth_code": "654321",
      "bank_code": "05",
      "rrn": "999",
      "ref_id": "777888",
      "message": "Authorization was approved",
      "amount": 100,
      "currency": "USD",
      "billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
      "gateway_id": 1,
      "status": "successful"
    },
    "avs_cvc_verification": {
      "avs_verification": {
        "result_code": "1"
      },
      "cvc_verification": {
        "result_code": "1"
      }
    },
    "customer": {
      "ip": "127.0.0.1",
      "email": "john@example.com",
      "device_id": "12312312321fff67",
      "birth_date": "1980-01-31"
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    }
  }
}