Запрос на взимание платы
Банки-эквайеры могут применять различные сценарии и типы транзакций при проведении оплаты по сохраненным картам для вашей схемы расчета. Это означает, что вам необходимо было бы внедрять разные типы запросов при работе с несколькими эквайерами или при смене одного эквайера на другого.
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-адрес клиента, производящего оплату на вашем сайте или в приложении. |
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/Minsk",
"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
}
}