3.21. /api/v2/sale

Введение

Оплата инициируется через запрос HTTPS POST на указанный ниже URL с использованием указанных параметров. Для аутентификации запроса используется SHA-1. См. Статусы транзакций.

API URL

Примечание

Путь 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

Параметры запроса оплаты

Примечание

Запрос должен иметь заголовок content-type=application/x-www-form-urlencoded.
Банк может переопределить необходимость некоторых полей, сделав их обязательными.
Пробелы в начале и в конце значений параметров будут отсечены.

Предупреждение

В значениях параметров необходимо экранировать следующие символы: & + «.

Название параметра

Описание

Значение

client_orderid

Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной.
Необходимость: Обязательно
Тип: String
Длина: 128

order_desc

Описание заказа.
Необходимость: Обязательно
Тип: String
Длина: 64k

amount

Сумма к оплате. Сумма должна быть указана в минимальных единицах с “.” разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек.
Необходимость: Обязательно
Тип: Numeric
Длина: 10

currency

Валюта, в которой проводится операция (см. Коды валют). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля.
Необходимость: Обязательно
Тип: String
Длина: 3

address1

Адрес Плательщика, строка 1. (Обратите внимание, что в некоторых случаях невозможно отправить адрес длиной более 50 символов. Для получения более подробной информации обратитесь к вашему менеджеру.)
Необходимость: Обязательно
Тип: String
Длина: 256

city

Город Плательщика.
Необходимость: Обязательно
Тип: String
Длина: 50

zip_code

Почтовый индекс Плательщика.
Необходимость: Обязательно
Тип: String
Длина: 10

country

Страна Плательщика. Для списка действительных кодов см. Коды стран
Необходимость: Обязательно
Тип: String
Длина: 2

phone

Полный международный номер телефона Плательщика, включая код страны.
Необходимость: Обязательно
Тип: String
Длина: 15

email

Адрес электронной почты Плательщика.
Необходимость: Обязательно
Тип: 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

Назначение платежа. Параметр может использоваться для указания пополняемого счёта (счета мобильных телефонов, игровые учётные записи и т. д.). Примеры значений: +9999999999; mail@example.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

Дополнительные параметры

Для Присоединяющейся Стороны

Примечание

Данные браузера для 3DS 2.X собираются системой Присоединяющейся Стороны на этапе 3DS аутентификации. Однако для некоторых каналов обработки браузерные данные и/или URL-адрес Присоединяющейся Стороны для результатов 3DS challenge должны быть указаны в изначальном запросе на проведение транзакции. Свяжитесь с менеджером службы поддержки, чтобы уточнить, следует ли включать эти параметры в параметры запроса.

Сайт Присоединяющейся Стороны должен точно заполнять информацию о браузере по каждой транзакции. Эти данные могут быть получены серверами Присоединяющейся Стороны. Убедитесь, что данные не изменены и не жестко запрограммированы, и что они уникальны для каждой транзакции.

Название параметра

Описание

Значение

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

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

tds_areq_notification_url, alias tds_cres_notification_url

Полный URL-адрес системы Присоединяющейся Стороны, которая получит сообщение CRes или сообщение об ошибке. Это сообщение CRes должно быть отправлено Payneteasy. См. Загрузка результата CRes.
Необходимость: Опционально
Тип: String
Длина: 256

Для платежных учреждений

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-байтный результат
Тип: String
Length: 19-28

tds_authentication_result_transaction_id

xid for 1.0.2 or dsTransID for 2.1.0/2.2.0
Тип: String
Length: 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 = Аутентификация/ Верификация Аккаунта отклонена, отказ Эмитента.
Тип: String
Length: 1

tds_authentication_result_message_version
Версия номера сообщения. Версия протокола идентификацтора. Это номер версии протокола, назначенного системой, посылающей сообщение. Версия номера сообщения назначается Сервером 3DS, который относит протокол к сообщению AReq. Версия номера сообщения не меняется во время процесса 3DS. Возможные значения:
- 1.0.2
- 2.1.0
- 2.2.0
Тип: String
Длина: 5

Параметры ответа

Примечание

Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра.

Название параметра

Описание

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]
&currency=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]
&currency=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
&currency=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

Конструктор запросов

endpointid or groupid

input ENDPOINTID or ENDPOINTGROUPID

client_orderid

make it or use internal invoice ID

order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount
email
currency
card_recurring_payment_id

use either RPI or card number, not both

ipaddress
site_url
credit_card_number

card_printed_name
expire_month
expire_year
cvv2
purpose
merchant_control

input Control Key

redirect_url
redirect_success_url
redirect_fail_url
notify_url
server_callback_url
merchant_data
dapi_imei

String to sign
Signature