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

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

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

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

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

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

Запрос

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

Параметр Тип Описание
request object
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 на стороне торговца, на который PayCross будет перенаправлять клиента после завершения 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, и PayCross передаст банку-эквайеру данные карты с 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, PayCross не применяет 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, PayCross принудительно применяет 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 - PayCross вернет токен карты для осуществления последующих платежей без повторного ввода реквизитов карты. Клиент указывает полные данные карты, включая проверочный код карты CVC/CVV, и проходит авторизацию по протоколу 3-D ­Secure только при проведении первоначального платежа;

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

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

card_on_file - PayCross вернет токен карты, чтобы сохранить его в учетной записи клиента на вашем сайте или в приложении и использовать этот токен для последующих платежей. Ознакомьтесь ниже с секцией 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).
Пример запроса 
{
  "request": {
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction",
    "tracking_id": "tracking_id_000",
    "credit_card": {
      "number": "5204240000015003",
      "verification_value": "123",
      "holder": "John Doe",
      "exp_month": 10,
      "exp_year": 2026
    },
    "additional_data": {
      "browser": {
        "screen_width": 1920,
        "screen_height": 1080,
        "screen_color_depth": 24,
        "language": "en",
        "java_enabled": false,
        "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
        "time_zone": -180,
        "time_zone_name": "Europe/Vilnius",
        "accept_header": "*/*",
        "window_height": 667,
        "window_width": 600
      }
    },
    "three_d_secure": {
      "advanced": false
    },
    "test": true
  }
}

Ответ

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

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

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

Info

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

Пример ответа на запрос на взимание платы 
{
    "uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "parent_uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "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": "2024-06-19T08:53:41.211Z",
    "updated_at": "2024-06-19T08:53:46.217Z",
    "paid_at": "2024-06-19T08:53:46.149Z",
    "expired_at": null,
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "https://gateway.pay-cross.com/process/c74e1b00-9b94-4682-82c3-60167ce64841",
    "credit_card": {
        "holder": "John Doe",
        "stamp": "a282993adc1299dacc79248e77e04c2995f79fcc9f82f408bec59ba20ff55739",
        "brand": "master",
        "last_4": "5003",
        "first_1": "5",
        "bin": "520424",
        "bin_8": "52042400",
        "issuer_country": null,
        "issuer_name": null,
        "product": null,
        "exp_month": 10,
        "exp_year": 2026,
        "token_provider": null,
        "token": null
    },
    "status_code": null,
    "gateway": {
        "iframe": true
    },
    "mute_notifications": null,
    "id": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "additional_data": {},
    "links": {
        "receipt_url": "https://admin.pay-cross.com/customer/transactions/c74e1b00-9b94-4682-82c3-60167ce64841/33724a6fe94fe937575c6ed18d2ab8abdc34732df17e51be6da88e9b37356101?language=en"
    },
    "code": "S.0000",
    "friendly_message": "The operation is successful.",
    "smart_routing_verification": {
        "status": "successful"
    },
    "charge": {
        "auth_code": "654321",
        "bank_code": "05",
        "rrn": "999",
        "ref_id": "777888",
        "message": "Payment was approved",
        "amount": 100,
        "currency": "USD",
        "billing_descriptor": "test descriptor",
        "gateway_id": 3483,
        "status": "successful"
    },
    "avs_cvc_verification": {
        "avs_verification": {
            "result_code": "1"
        },
        "cvc_verification": {
            "result_code": "1"
        }
    },
    "customer": {
        "ip": null,
        "email": null,
        "device_id": null,
        "birth_date": null,
        "taxpayer_id": null,
        "external_id": null,
        "first_name": null,
        "last_name": null,
        "address": null,
        "country": null,
        "city": null,
        "zip": null,
        "state": null,
        "phone": null
    },
    "billing_address": {
        "first_name": null,
        "last_name": null,
        "address": null,
        "country": null,
        "city": null,
        "zip": null,
        "state": null,
        "phone": null
    }
}