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 |
Параметры запроса оплаты
Note
Warning
В значениях параметров необходимо экранировать следующие символы: & + “.
Название параметра |
Описание |
Значение |
---|---|---|
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.
|
Необходимость : ОпциональноТип : 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 в режиме Payment Gateway. |
Необходимость : ОпциональноТип : IntДлина : 10 |
merchant_customer_identifier |
Идентификатор клиента в системе CMS, назначенный Присоединяющейся Стороной. Параметр становится обязательным, если включена система CMS в режиме CRM. |
Необходимость : ОпциональноТип : VarcharДлина : 64 |
Дополнительные параметры
Для Присоединяющейся Стороны
Note
Сайт Присоединяющейся Стороны должен точно заполнять информацию о браузере по каждой транзакции. Эти данные могут быть получены серверами Присоединяющейся Стороны. Убедитесь, что данные не изменены и не жестко запрограммированы, и что они уникальны для каждой транзакции.
Название параметра |
Описание |
Значение |
---|---|---|
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 аутентификации происходит на их стороне.
Parameter Name |
Description |
Value |
---|---|---|
tds_authentication_result_type |
Type of result. Possible values are:
- SIMPLE
|
Type : StringLength : 6 |
tds_authentication_result_authentication_type |
Authentication Type. Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. Possible values are:
- 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
|
Type : StringLength : 2 |
tds_authentication_result_authentication_value |
Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result |
Type : StringLength : 19-28 |
tds_authentication_result_transaction_id |
xid for 1.0.2 or dsTransID for 2.1.0/2.2.0 |
Type : StringLength : 19-36 |
tds_authentication_result_transaction_status |
Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:
- 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 = Attempts Processing Performed, Not Authenticated/Verified, but a proof of attempted authentication/verification is provided
- C = Challenge Required, Additional authentication is required using the CReq/CRes
- D = Challenge Required, Decoupled Authentication confirmed
- R = Authentication/ Account Verification Rejected, Issuer is rejecting
|
Type : StringLength : 1 |
tds_authentication_result_message_version |
Message Version Number. Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction. Possible values are:
- 1.0.2
- 2.1.0
- 2.2.0
|
Type : StringLength : 5 |
Параметры ответа
Note
Название параметра |
Описание |
---|---|
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=john.smith@gmail.com
¤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=john.smith@gmail.com
¤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 |
---|
|