3.14. /api/v2/sale

Введение

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

API URL

Примечание

Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее.

Интеграционная среда

Производственная среда

https://sandbox.payneteasy.ru/paynet/api/v2/sale/ENDPOINTID

https://gate.payneteasy.ru/paynet/api/v2/sale/ENDPOINTID

https://sandbox.payneteasy.ru/paynet/api/v2/sale/group/ENDPOINTGROUPID

https://gate.payneteasy.ru/paynet/api/v2/sale/group/ENDPOINTGROUPID

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

Примечание

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

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

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

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

Описание

Значение

client_orderid

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

order_desc

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

amount

Сумма к оплате. Сумма должна быть указана в наибольших единицах с разделителем .. Например, 10.5 для USD означает 10 долларов США и 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> (См.: URL запроса)
2. Параметр запроса: client_orderid
3. Параметр запроса: amount в минимальных денежных единицах
4. Параметр запроса: email
5. merchant_control (Контрольный ключ, назначенный для учетной записи Присоединяющейся стороны в 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-адрес, на который будет перенаправлен Плательщик после завершения транзакции. Перенаправление выполняется в любом случае, независимо от того, получила ли транзакция статус successful, unsuccessful или любой другой конечный статус (см. Статусы транзакций).
Присоединяющаяся Сторона не должна использовать параметры, которые посылаются вместе с HTTP-запросом перенаправления на обработку статуса транзакции. Вместо этого Присоединяющаяся Сторона может использовать server_callback_url или АПИ команду запроса статуса. Если же нет необходимости перенаправлять Плательщика, вписать http://https://doc.payneteasy.ru. Использовать или параметр redirect_url, или комбинацию параметров redirect_success_url и redirect_fail_url, не оба.
Необходимость: Опционально
Тип: String
Длина: 1024

redirect_success_url
URL-адрес, на который будет перенаправлен Плательщик после получения успешного статуса транзакции (см. Статусы транзакций).
Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата плательщика, параметр может быть использован со значением http://https://doc.payneteasy.ru. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.
Необходимость: Опционально
Тип: String
Длина: 1024

redirect_fail_url
URL-адрес, на который будет перенаправлен Плательщик после получения неуспешного статуса транзакции (см. Статусы транзакций).
Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата плательщика, параметр может быть использован со значением http://https://doc.payneteasy.ru. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.
Необходимость: Опционально
Тип: String
Длина: 1024

ssn

Последние четыре цифры номера социального страхования Плательщика.
Необходимость: Опционально
Тип: Numeric
Длина: 32

birthday

Дата рождения Плательщика в формате YYYYMMDD.
Необходимость: Опционально
Тип: Numeric
Длина: 8

cell_phone

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

site_url

URL-адрес сайта электронной коммерции, откуда происходит платеж.
Необходимость: Опционально
Тип: String
Длина: 128

purpose

Назначение платежа. Параметр может использоваться для указания пополняемого счёта (счета мобильных телефонов, игровые учётные записи и т. д.). Примеры значений:+9999999999; mail@example.com и т. д. Это значение может проверяться системой защиты от мошенничества.
Необходимость: Опционально
Тип: String
Длина: 128

server_callback_url
URL-адрес server_callback_url, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся стороны. Данный параметр может быть передан вместо notify_url. При использовании server_callback_url платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. При использовании notify_url платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.).
Необходимость: Опционально
Тип: String
Длина: 1024

notify_url
URL-адрес notify_url, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся стороны. Данный параметр может быть передан вместо server_callback_url. При использовании notify_url платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). При использовании server_callback_url платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции.
Необходимость: Опционально
Тип: String
Длина: 1024

order_desc
Дополнительные сведения о транзакции для Присоединяющейся Стороны, которые можно прикрепить к транзакции и получить обратно в ответе на запрос статуса, обратном вызове Присоединяющейся Стороны или server_callback_url. Может содержать данные, которые будут полезны во внешней системе Присоединяющейся Стороны, например 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

Hosted Fields Parameters

When the card is collected with Hosted Fields, the Connecting Party does not have the card data: the request carries the hosted_fields_token received from the Hosted Fields SDK instead of the card parameters. The other parameters from Параметры запроса are sent as usual. The control checksum does not include card data and is calculated as usual.

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

Описание

Значение

hosted_fields_token

The hostedFieldsToken received from the Hosted Fields SDK. The Payment Gateway takes the card number, expiry date and CVV from it. Valid for 5 minutes, single use: a second request with the same token is rejected.
Необходимость: Условно
Тип: String
Длина: 2048

When hosted_fields_token is sent, these rules take precedence over the necessity of the card parameters in Параметры запроса.

Rule

Detail

A single source of card data

hosted_fields_token replaces credit_card_number, temporary_card_record_id and card_recurring_payment_id. Two of them at once are rejected with «At most one of credit_card_number, card_recurring_payment_id, temporary_card_record_id or hosted_fields_token should be set.»

expire_month and expire_year must not be sent

The expiry date comes from the token. Sending it as well is rejected with «When hosted_fields_token present expire_month and expire_year should not be set.»

cvv2 must not be sent

The CVV comes from the token. Sending it as well is rejected with «When hosted_fields_token present cvv2 should not be set.»

card_printed_name is not required

The Hosted Fields SDK does not collect the cardholder name. If the Connecting Party form has such a field, it is sent as card_printed_name; with hosted_fields_token it may also be omitted altogether.

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

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

Примечание

Данные браузера для 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, псевдоним 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 для 1.0.2 или dsTransID для 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 = 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
Тип: 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

Идентификатор заказа, присвоенный Payneteasy.

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
&currency=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.ru
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.payneteasy.ru%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.ru
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

Request with Hosted Fields Token Example

POST /paynet/api/v2/sale/39529 HTTP/1.1
Host: sandbox.payneteasy.ru
User-Agent: curl/7.83.0
Accept: */*
Content-Type: application/x-www-form-urlencoded
Connection: close

hosted_fields_token=eyJhbGciOi...
&client_orderid=34T43R77N
&order_desc=Test Order Описание
&first_name=John
&last_name=Smith
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&amount=156
&email=john.smith@gmail.com
&currency=RUB
&ipaddress=65.153.12.232
&redirect_url=http%3A%2F%2Fhttps://doc.payneteasy.ru%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399

Пример успешного ответа

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

Open API Collection

Open this method in the OpenAPI Reference

View in OpenAPI

Коллекция 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