3.21. /api/v2/sale
Введение
Оплата инициируется через запрос HTTPS POST на указанный ниже URL с использованием указанных параметров. Для аутентификации запроса используется SHA-1. См. Статусы транзакций.
API URL
Примечание
Интеграционная среда |
Производственная среда |
---|---|
https://sandbox.payneteasy.com/paynet/api/v2/sale/ENDPOINTID |
https://gate.payneteasy.com/paynet/api/v2/sale/ENDPOINTID |
https://sandbox.payneteasy.com/paynet/api/v2/sale/group/ENDPOINTGROUPID |
https://gate.payneteasy.com/paynet/api/v2/sale/group/ENDPOINTGROUPID |
Параметры запроса оплаты
Примечание
Предупреждение
В значениях параметров необходимо экранировать следующие символы: & + «.
Название параметра |
Описание |
Значение |
---|---|---|
client_orderid |
Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной. |
Необходимость : ОбязательноТип : StringДлина : 128 |
order_desc |
Описание заказа. |
Необходимость : ОбязательноТип : StringДлина : 64k |
amount |
Сумма к оплате. Сумма должна быть указана в минимальных единицах с “.” разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек. |
Необходимость : ОбязательноТип : NumericДлина : 10 |
currency |
Валюта, в которой проводится операция (см. Коды валют). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля. |
Необходимость : ОбязательноТип : StringДлина : 3 |
address1 |
Адрес Плательщика, строка 1. |
Необходимость : ОбязательноТип : StringДлина : 50 |
city |
Город Плательщика. |
Необходимость : ОбязательноТип : StringДлина : 50 |
zip_code |
Почтовый индекс Плательщика. |
Необходимость : ОбязательноТип : StringДлина : 10 |
country |
Страна Плательщика. Для списка действительных кодов см. Коды стран |
Необходимость : ОбязательноТип : StringДлина : 2 |
phone |
Полный международный номер телефона Плательщика, включая код страны. |
Необходимость : ОбязательноТип : StringДлина : 15 |
Адрес электронной почты Плательщика. |
Необходимость : ОбязательноТип : StringДлина : 50 |
|
ipaddress |
IP-адрес плательщика, также включен в проверки на мошенничество. |
Необходимость : ОбязательноТип : StringДлина : 45 |
control |
Контрольная сумма, сгенерированная SHA-1. Строка для подписи представляет собой объединение следующих параметров:
1. <ENDPOINTID | ENDPOINTGROUPID> (см: Request URL)
2. Параметр запроса: client_orderid
3. Параметр запроса: amount в минимальных денежных единицах
4. Параметр запроса: email
5. merchant_control (Контрольный ключ, назначенный для учетной записи Присоединяющейся Cтороны в Payneteasy).
|
Необходимость : ОбязательноТип : StringДлина : 40 |
cvv2 |
CVV2-код Плательщика. CVV2 (Card Verification Значение) — это трех- или четырех-значное число ПОСЛЕ номера кредитной карты в области подписи карты. |
Необходимость : ОбязательноТип : NumericДлина : 3-4 |
credit_card_number |
Номер банковской карты Плательщика. Нужно отправлять или комбинацию из credit_card_number, card_printed_name, expire_month и expire_year или параметр card_recurring_payment_id, но не все в одном запросе. |
Необходимость : УсловноТип : NumericДлина : 20 |
card_recurring_payment_id |
Токенизированный идентификатор владельца карты. Нужно отправлять или параметр card_recurring_payment_id или комбинацию из credit_card_number, card_printed_name, expire_month и expire_year, но не все в одном запросе. Для создания card_recurring_payment_id см. /api/v4/create-card-ref. |
Необходимость : УсловноТип : LongДлина : 20 |
card_printed_name |
Имя владельца карты, напечатанное на банковской карте. |
Необходимость : УсловноТип : StringДлина : 128 |
expire_month |
Месяц окончания срока действия банковской карты. |
Необходимость : УсловноТип : NumericДлина : 2 |
expire_year |
Год окончания срока действия банковской карты. |
Необходимость : УсловноТип : NumericДлина : 4 |
first_name |
Имя Плательщика. Необходимость параметра можно уточнить у отдела поддержки. Зависит от канала эквайринга. |
Необходимость : ОбязательноТип : StringДлина : 50 |
last_name |
Фамилия Плательщика. Необходимость параметра можно уточнить у отдела поддержки. Зависит от канала эквайринга. |
Необходимость : ОбязательноТип : StringДлина : 50 |
state |
Штат Плательщика. Для списка действительных кодов штатов см. Обязательные коды штатов. Требуется для США, Канады и Австралии. |
Необходимость : УсловноТип : StringДлина : 2-3 |
redirect_url |
URL-адрес, на который будет перенаправлен Плательщик после завершения транзакции. Перенаправление выполняется в любом случае, независимо от того, получила ли транзакция успешный, неуспешный или любой другой конечный статус (см. Статусы транзакций).
Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата «плательщика, параметр может быть использован со значением https://doc.payneteasy.com. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.
|
Необходимость : ОпциональноТип : StringДлина : 1024 |
redirect_success_url |
URL-адрес, на который будет перенаправлен Плательщик после получения успешного статуса транзакции.(cм. Статусы транзакций).
Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата плательщика, параметр может быть использован со значением http://https://doc.payneteasy.com. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.
|
Необходимость : ОпциональноТип : StringДлина : 1024 |
redirect_fail_url |
URL-адрес, на который будет перенаправлен Плательщик после получения неуспешного статуса транзакции.(cм. Статусы транзакций).
Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции.Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата плательщика, параметр может быть использован со значением http://https://doc.payneteasy.com. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.
|
Необходимость : ОпциональноТип : StringДлина : 1024 |
ssn |
Последние четыре цифры номера социального страхования Плательщика. |
Необходимость : ОпциональноТип : NumericДлина : 32 |
birthday |
Дата рождения Плательщика в формате ГГГГММДД. |
Необходимость : ОпциональноТип : NumericДлина : 8 |
cell_phone |
Полный номер мобильного телефона Плательщика, включая код страны. |
Необходимость : ОпциональноТип : StringДлина : 15 |
site_url |
URL-адрес сайта электронной коммерции, откуда происходит платеж. |
Необходимость : ОпциональноТип : StringДлина : 128 |
purpose |
Назначение платежа. Параметр может использоваться для указания пополняемого счёта (счета мобильных телефонов, игровые учётные записи и т. д.). Примеры значений: +7123456789; gamer0001@ereality.com и т. д. Это значение может проверяться системой защиты от мошенничества. |
Необходимость : ОпциональноТип : StringДлина : 128 |
server_callback_url |
URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны).Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся cтороны.Данный параметр может быть передан вместо notify_url. При использовании server_callback_url платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. При использовании notify_url платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.)
|
Необходимость : ОпциональноТип : StringДлина : 1024 |
notify_url |
URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны).Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся cтороны.Данный параметр может быть передан вместо server_callback_url. При использовании notify_url платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). При использовании server_callback_url платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции.
|
Необходимость : ОпциональноТип : StringДлина : 1024 |
merchant_data |
Дополнительные сведения о транзакции для Присоединяющейся Стороны, которые можно прикрепить к транзакции и получить обратно в ответе на запрос статуса или обратном вызове. Может содержать данные, которые будут полезны во внешней системе Присоединяющейся Стороны, например VIP клиент, телевизионная промо-кампания.
Информация возвращается в ответе на запрос статуса и в обратном вызове Присоединяющейся Стороны.
|
Необходимость : ОпциональноТип : StringДлина : 64k |
dapi_imei |
Уникальный идентификатор устройства. |
Необходимость : ОпциональноТип : StringДлина : 32 |
minimum_transaction_amount |
Этот параметр можно использовать для ограничения минимальной суммы транзакции, если сумма транзакции доступна для указания Плательщиком в форме. Свяжитесь с менеджером службы поддержки, чтобы включить эту функцию. Формат значения такой же, как и в параметре amount. |
Необходимость : ОпциональноТип : NumericДлина : 10 |
maximum_transaction_amount |
Этот параметр можно использовать для ограничения максимальной суммы транзакции, если сумма транзакции доступна для указания Плательщиком в форме. Свяжитесь с менеджером службы поддержки, чтобы включить эту функцию. Формат значения такой же, как и в параметре amount. |
Необходимость : ОпциональноТип : NumericДлина : 10 |
customer_level |
Уровень клиента в системе CMS. |
Необходимость : ОпциональноТип : VarcharДлина : 32 |
customer_id |
Идентификатор клиента в системе CMS. Параметр становится обязательным, если включена система CMS в режиме определения клиента Платёжным шлюзом. |
Необходимость : ОпциональноТип : IntДлина : 10 |
merchant_customer_identifier |
Идентификатор клиента в системе CMS, назначенный Присоединяющейся Стороной. Параметр становится обязательным, если включена система CMS в режиме CRM. |
Необходимость : ОпциональноТип : VarcharДлина : 64 |
recurring-payment-id |
Recurring Payment ID может быть передан вместо данных держателя карты. Для нативных транзакций CVV не требуется. Обновление данных клиента возможно через /api/v4/update-recurring-payment/. Процесс создания Recurring Payment ID инициируется HTTPS POST запросом с использованием указанных ниже URLs. и параметров, используйте OAuth RSA-SHA256 для аутентификация |
Необходимость : УсловноТип : Long |
Дополнительные параметры
Для Присоединяющейся Стороны
Примечание
Сайт Присоединяющейся Стороны должен точно заполнять информацию о браузере по каждой транзакции. Эти данные могут быть получены серверами Присоединяющейся Стороны. Убедитесь, что данные не изменены и не жестко запрограммированы, и что они уникальны для каждой транзакции.
Название параметра |
Описание |
Значение |
---|---|---|
ipaddress |
IP-адрес браузера, возвращаемый HTTP-заголовками инициатору запроса 3DS. |
Необходимость : ОбязательноТип : StringДлина : 45 |
customer_browser_accept_header |
Точное содержание заголовков HTTP Accept, отправленное инициатору запроса 3DS из браузера владельца карты. |
Необходимость : ОбязательноТип : StringДлина : 2048 |
customer_browser_javascript_enabled |
Boolean, представляющий cпособность браузера владельца карты запускать JavaScript. |
Необходимость : ОбязательноТип : BooleanДлина : - |
customer_browser_accept_language |
Значение, представляющее язык браузера, по определено IETF BCP47. |
Необходимость : ОбязательноТип : StringДлина : 8 |
customer_browser_user_agent |
Точное содержание заголовка HTTP user-agent. |
Необходимость : ОбязательноТип : StringДлина : 2048 |
tds_areq_notification_url, alias tds_cres_notification_url |
Полный URL-адрес системы Присоединяющейся Стороны, которая получит сообщение CRes или сообщение об ошибке. Это сообщение CRes должно быть отправлено Payneteasy. См. Загрузка результата CRes. |
Необходимость : ОпциональноТип : StringДлина : 256 |
customer_browser_info |
Если значение - true, то поля ниже должны присутствовать. |
Необходимость : ОпциональноТип : BooleanДлина : - |
customer_browser_color_depth |
Значение, представляющее разрядность цветовой палитры для отображения изображений, в битах на пиксель. Становится обязательным, когда browser_javaScript_enabled = true». |
Необходимость : ОпциональноТип : StringДлина : 2 |
customer_browser_java_enabled |
Boolean, который представляет способность браузера владельца карты запускать Java. Становится обязательным, когда browser_javaScript_enabled = true. |
Необходимость : ОпциональноТип : BooleanДлина : - |
customer_browser_screen_height |
Общая высота экрана владельца карты в пикселях. Требуется, когда browser_javaScript_enabled = true. |
Необходимость : ОпциональноТип : NumericДлина : 6 |
customer_browser_screen_width |
Общая ширина экрана владельца карты в пикселях. Требуется, когда browser_javaScript_enabled = true. |
Необходимость : ОпциональноТип : NumericДлина : 6 |
customer_browser_time_zone |
Смещение часового пояса в минутах между UTC и местным временем браузера держателя карты. Обратите внимание, что смещение является положительным, если местный часовой пояс отстает от UTC, и отрицательным, если он опережает UTC. Становится обязательным, когда browser_javaScript_enabled = true. |
Необходимость : ОпциональноТип : StringДлина : 5 |
Для платежных учреждений
PSP или эквайер могут заполнить результаты 3DS для каждой транзакции, если выполнение 3DS аутентификации происходит на их стороне.
Название параметра |
Описание |
Значение |
---|---|---|
tds_authentication_result_type |
Тип результата. Возможное значение:
- SIMPLE
|
Тип : StringДлина : 6 |
tds_authentication_result_authentication_type |
Тип Аутентификации. Показывает тип метода аутентификации, используемый Эмитентом, для отправки ARes сообщения или использованный ACS при отправке RReq сообщения. Возможные значения:
- 01 = Static
- 02 = Dynamic
- 03 = OOB
- 04 = Decoupled
- 05-79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
- 80-99 = Reserved for DS use
|
Тип : StringДлина : 2 |
tds_authentication_result_authentication_value |
Значение Аутентификации. Зависищее от Платежной Системы значение, определяемое ACS или DS, используя алгоритмы, определенные Платежной Системой. Значение Аутентификации может быть использовано как подтверждение аутентификации. 20-байтное значение, закодированное Base64, выдающее 28-байтный результат |
Тип : StringLength : 19-28 |
tds_authentication_result_transaction_id |
xid for 1.0.2 or dsTransID for 2.1.0/2.2.0 |
Тип : StringLength : 19-36 |
tds_authentication_result_transaction_status |
Статус транзакции. Показывает, транзакция аутентифицирована или верифицирована. Возможные значения:
- Y = Authentication Verification Successful
- N = Not Authenticated/Account Not Verified, Transaction denied
- U = Authentication/Account Verification Could Not Be Performed, Technical or other problem, as indicated in ARes or RReq
A = Произведена попытка обработки, Не Аутентифицирована/Верифицирована , но подтверждение попытки аутентификации/верификации предоставлено.
- C = Challenge Required, Additional authentication is required using the CReq/CRes
- D = Challenge Required, Decoupled Authentication confirmed
R = Аутентификация/ Верификация Аккаунта отклонена, отказ Эмитента.
|
Тип : StringLength : 1 |
tds_authentication_result_message_version |
Версия номера сообщения. Версия протокола идентификацтора. Это номер версии протокола, назначенного системой, посылающей сообщение. Версия номера сообщения назначается Сервером 3DS, который относит протокол к сообщению AReq. Версия номера сообщения не меняется во время процесса 3DS. Возможные значения:
- 1.0.2
- 2.1.0
- 2.2.0
|
Тип : StringДлина : 5 |
Параметры ответа
Примечание
Название параметра |
Описание |
---|---|
type |
Тип ответа. Может принимать такие значения как: async-response, validation-error, error и т.д.
Если тип равен validation-error или error, параметры error-message и error-code будут содержать сведения об ошибке.
|
paynet-order-id |
Номер заказа в системе gate.payneteasy.com. |
merchant-order-id |
Номер заказа в системе Присоединяющейся Стороны. |
serial-number |
Уникальный номер, присвоенный сервером Payneteasy конкретному запросу от Присоединяющейся Стороны. |
error-message |
Для транзакций в статусе declined или error, этот параметр будет содержать причину отклонения или сведения об ошибке. |
error-code |
Код ошибки для транзакций в статусе declined или error. |
end-point-id |
Идентификатор терминала, используемый для транзакции. |
Пример запроса с данными владельца карты
POST /paynet/api/v2/sale/39529 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
credit_card_number=4538977399606732
&card_printed_name=John
&expire_month=01
&expire_year=2042
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Описание
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=[email protected]
¤cy=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.com
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.payneteasy.com%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&merchant_data=VIP customer
&dapi_imei=123
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399
POST /paynet/api/v2/sale/39529 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
&client_orderid=34T43R77N
&order_desc=Test Order Описание
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&[email protected]
¤cy=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.com
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.payneteasy.com%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&merchant_data=VIP customer
&dapi_imei=123
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399
Пример запроса с идентификатором регулярного платежа по карте
POST /paynet/api/v2/sale/39915 HTTP/1.1
Host: sandbox.payneteasy.com
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 317
Content-Type: application/x-www-form-urlencoded
Connection: close
card_recurring_payment_id=1491954
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Описание
&amount=777
¤cy=USD
&ipaddress=65.153.12.232
&redirect_url=http://doc2.doc2.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=80761544c64373d1624240add048d36d42fe528a
Пример успешного ответа
HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 11:03:17 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip
type=async-response
&serial-number=00000000-0000-0000-0000-000002d9b22a
&merchant-order-id=inv4097763
&paynet-order-id=6768788
&end-point-id=22903
Пример неуспешного ответа
HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 13:14:40 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip
type=validation-error
&serial-number=00000000-0000-0000-0000-000002b36f64
&merchant-order-id=inv4097763
&error-message=End+point+with+id+22903+not+found
&error-code=3
Коллекция Postman
Конструктор запросов
String to sign |
---|
Signature |
---|
|