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-адрес, по которому будет отправлен обратный вызов с результатом транзакции.
Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to Connecting Party callback parameters.
This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc).
|
Необходимость : ОпциональноТип : StringДлина : 1024 |
notify_url |
URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции.
Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to notify_url refer to Connecting Party callback parameters.
This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status.
|
Необходимость : ОпциональноТип : 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 can be sent instead of cardholder data. CVV for native is not needed. Customer Data can be updated via /api/v4/update-recurring-payment/. Recurring Payment ID creation is initiated through HTTPS POST request by using URLs and the parameters specified below. Use OAuth RSA-SHA256 for authentication. |
Необходимость : УсловноТип : 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. См.:ref:Загрузка результата CRes :ref:`CRes</api/3ds/v1/upload-cres-result/>. |
Необходимость : ОпциональноТип : 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 |
---|
|