3.22. /api/v2/sale-form

Введение

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

API URL

Примечание

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

Интеграционная среда	Производственная среда
https://sandbox.payneteasy.com/paynet/api/v2/sale-form/ENDPOINTID	https://gate.payneteasy.com/paynet/api/v2/sale-form/ENDPOINTID
https://sandbox.payneteasy.com/paynet/api/v2/sale-form/group/ENDPOINTGROUPID	https://gate.payneteasy.com/paynet/api/v2/sale-form/group/ENDPOINTGROUPID

Параметры запроса оплаты с использованием формы

Примечание

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

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

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

Название параметра	Описание	Значение
client_orderid	Уникальный идентификатор заказа в системе Присоединяющейся Стороны.	`Необходимость`: Обязательно `Тип`: String `Длина`: 128
order_desc	Описание заказа.	`Необходимость`: Обязательно `Тип`: String `Длина`: 64k
first_name	Имя Плательщика. Необходимость параметра зависит от канала эквайринга и необходимость параметра, необходимо уточнять у техподдержки.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
last_name	Фамилия Плательщика. Необходимость параметра зависит от канала эквайринга и необходимость параметра, необходимо уточнять у техподдержки.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
ssn	Последние четыре цифры номера социального страхования Плательщика.	`Необходимость`: Опционально `Тип`: Numeric `Длина`: 32
birthday	Дата рождения Плательщика в формате ГГГГММДД.	`Необходимость`: Опционально `Тип`: Numeric `Длина`: 8
address1	Адрес Плательщика срока 1.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
city	Город Плательщика.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
state	Штат Плательщика. Для списка действительных кодов штатов см. Обязательные коды штатов. Требуется для США, Канады и Австралии.	`Необходимость`: Условно `Тип`: String `Длина`: 2
zip_code	Почтовый индекс Плательщика.	`Необходимость`: Обязательно `Тип`: String `Длина`: 10
country	Страна Плательщика. Для списка действительных кодов см. Коды стран	`Необходимость`: Обязательно `Тип`: String `Длина`: 2
phone	Полный международный номер телефона Плательщика, включая код страны.	`Необходимость`: Обязательно `Тип`: String `Длина`: 15
cell_phone	Полный номер мобильного телефона Плательщика, включая код страны.	`Необходимость`: Опционально `Тип`: String `Длина`: 15
email	Адрес электронной почты Плетельщика.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
purpose	Назначение платежа. Параметр может использоваться для указания пополняемого счёта (счета мобильных телефонов, игровые учётные записи и т. д.). Примеры значений: +7123456789; gamer0001@ereality.com и т. д. Это значение может проверяться системой защиты от мошенничества.	`Необходимость`: Опционально `Тип`: String `Длина`: 128
amount	Сумма к оплате. Сумма должна быть указана в максимальных единицах с “.” разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек.	`Необходимость`: Обязательно `Тип`: Numeric `Длина`: 10
currency	Валюта, в которой проводится операция (см. Коды валют). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля.	`Необходимость`: Обязательно `Тип`: String `Длина`: 3
ipaddress	IP-адрес плательщика, также включен в проверки на мошенничество.	`Необходимость`: Обязательно `Тип`: String `Длина`: 20
site_url	URL-адрес сайта электронной коммерции, откуда происходит платеж.	`Необходимость`: Опционально `Тип`: String `Длина`: 128
control	Контрольная сумма, сгенерированная SHA-1. Строка для подписи представляет собой объединение следующих параметров: 1. <ENDPOINTID \| ENDPOINTGROUPID> (см: URL), 2. Параметр запроса: client_orderid, 3. Параметр запроса: amount в минимальных денежных единицах, 4. Параметр запроса: email, 5. merchant_control (Контрольный ключ, назначенный для учетной записи Присоединяющейся стороны в Payneteasy).	`Необходимость`: Обязательно `Тип`: String `Длина`: 40
redirect_url	URL-адрес, на который будет перенаправлен Плательщик после завершения транзакции. Перенаправление выполняется в любом случае, независимо от того, получила ли транзакция успешный, неуспешный или любой другой конечный статус (см. Статусы транзакций). Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата плательщика, параметр может быть использован со значением http://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
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-адрес, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны).Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся cтороны.Этот параметр может быть отправлен вместо server_callback_url. Если отправлен server_callback_url, Платёжный шлюз совершает обратный вызов только после получения финального статуса по изначальной транзакции. Если отправлен notify_url, Платёжный шлюз совершает обратный вызов после получения финального статуса по изначальной транзакции, а также по всем последующим событиям, связанным с этой транзакцией (возврат, принудительный возврат, и т.д.).	`Необходимость`: Опционально `Тип`: String `Длина`: 1024
preferred_language	Двухбуквенный код языка Плательщика для многоязычных платежных форм.	`Необходимость`: Опционально `Тип`: String `Длина`: 2
order_desc	Дополнительные сведения о транзакции для Присоединяющейся Стороны, которые можно прикрепить к транзакции и получить обратно в ответе на запрос статуса или обратном вызове. Может содержать данные, которые будут полезны во внешней системе Присоединяющейся Стороны, например VIP клиент, телевизионная промо-кампания. Information returns in Status response and Connecting Party Callback.	`Необходимость`: Опционально `Тип`: String `Длина`: 64k
merchant_form_data	Ключи и значения, отправленные в параметре MERCHANT_FORM_DATA, делятся на макросы с тем же именем. Параметр должен использовать URL кодировку (urlencode), например: testparam%3Dtest1%26mynewparam%3Dtest2 делится на макросы $MFD_testparam = test1 и $MFD_mynewparam = test2 в форме.Символы ключей параметра [a-zA-Z0-9], символы значений параметра [a-zA-Z0-9], управляющие символы [=&], максимальный размер 2 МБ. Например, этот параметр можно использовать для отображения формы платежа в светлом/темном режиме в зависимости от переданного значения (для переданного параметра merchant_form_data=theme%3Ddark, вместо макроса $MFD_theme в форме оплаты будет значение dark.	`Необходимость`: Опционально `Тип`: String `Длина`: 128
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
card_recurring_payment_id	Токенизированная платёжная информация держателя карты, также упоминающаяся как Идентификатор Повторного Платежа или Recurring Payment ID (RPI). Может быть создан с помощью запроса токенизации v4.	`Необходимость`: Условно `Тип`: Int
cardrefid	Ссылочный Идентификатор Платежа для последующих списаний. Может быть создан с помощью запроса токенизации v4 или запроса токенизации v2.	`Необходимость`: Условно `Тип`: Int

For Faster Payments System (СБП) integration use purpose field for fpsRequestId parameter.

Параметры запроса страхования

Примечание

Эквайер может переопределить обязательность некоторых полей.

Ведущий и замыкающий пробельные символы во входных параметрах будут отсечены.

Название параметра	Описание	Значение
insurance_amount	Сумма к страхованию. Сумма должна быть указана в минимальных единицах с . разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек.	`Тип`: Numeric `Длина`: 10
insured_person_first_name	Имя страхователя	`Тип`: String `Длина`: 256
insured_person_last_name	Фамилия страхователя	`Тип`: String `Длина`: 256
insured_person_middle_name	Отчество страхователя	`Тип`: String `Длина`: 256
insured_person_birthday	Дата рождения страхователя	`Тип`: String `Длина`: 256
insured_person_document_series	Серия документа страхователя	`Тип`: String `Длина`: 256
insured_person_document_number	Номер документа страхователя	`Тип`: String `Длина`: 256
insured_person_document_issue_date	Дата выдачи документа страхователя	`Тип`: String `Длина`: 256
insured_person_document_issuer_name	Кем выдан документ страхователя	`Тип`: String `Длина`: 256
insured_person_document_issuer_code	Код подразделения отделения, выдавшего документ страхователя	`Тип`: String `Длина`: 256
insured_person_registration_address	Адрес регистрации страхователя	`Тип`: String `Длина`: 256
insured_person_phone	Телефон страхователя	`Тип`: String `Длина`: 256
insured_person_email	Электронная почта страхователя	`Тип`: String `Длина`: 256
card_insurance_agreement_number	Номер договора	`Тип`: String `Длина`: 256
card_insurance_agreement_sell_date	Дата продажи	`Тип`: String `Длина`: 256
card_insurance_agreement_start_date	Дата начала договора	`Тип`: String `Длина`: 256
card_insurance_agreement_end_date	Дата окончания договора	`Тип`: String `Длина`: 256
card_insurance_agreement_amount	Страховая сумма	`Тип`: String `Длина`: 256
card_insurance_agreement_bonus	Страховая премия	`Тип`: String `Длина`: 256

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

Примечание

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

Название параметра	Описание
type	Тип ответа. Может принимать такие значения как async-form-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.
redirect-url	URL-адрес страницы, на которую Присоединяющаяся сторона должна перенаправить браузер клиента методом HTTP 302.

Пример запроса

POST /paynet/api/v2/sale-form/39519 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close

client_orderid=inv1409911
&order_desc=Test Order Описание
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=[email protected]
&currency=USD
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.com
&purpose=user_account1
&redirect_url=http://connectingparty.com/result
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2
&control=185aea68b751221b78fa9138e9d44a6aa4c2c446

Пример запроса со страхованием

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=10.42
&insurance_amount=10
&[email protected]
&currency=AED
&ipaddress=65.153.12.232
&site_url=www.google.com
&purpose=user_account1
&redirect_url=https://doc.payneteasy.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2
&insured_person_first_name=John
&insured_person_last_name=Doe
&insured_person_middle_name=J
&insured_person_birthday=19820115
&insured_person_document_series=4111
&insured_person_document_number=562297
&insured_person_document_issue_date=19970117
&insured_person_document_issuer_name=First document department
&insured_person_registration_address=Seattle 100 Main st
&insured_person_phone=+12063582043
&[email protected]
&card_insurance_agreement_number=210H3FIM2426726391
&card_insurance_agreement_sell_date=20210115
&card_insurance_agreement_start_date=20210116
&card_insurance_agreement_end_date=20250115
&card_insurance_agreement_amount=20000
&card_insurance_agreement_bonus=4000
&control=c1ac1d532c96ddde35ad87be8b80a3d5aa0f2f48

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

HTTP/1.1 200 OK
Server: server
Date: Tue, 11 Oct 2022 14:25:25 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 280

type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddb0b9
&merchant-order-id=Test
&paynet-order-id=6863099
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.com%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A68633370432F786752582F6154674965594A696F4D41306C50596E334F5453553D

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

HTTP/1.1 200 OK
Server: server
Date: Tue, 11 Oct 2022 14:16:06 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 170

type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb0b7
&error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD
&error-code=16

Коллекция Postman

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

Insurance

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
ipaddress
site_url
purpose
merchant_control	input Control Key
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data
cardrefid
maximum-transaction-amount
minimum-transaction-amount
merchant_form_data
insurance_amount
insured_person_first_name
insured_person_last_name
insured_person_middle_name
insured_person_birthday
insured_person_document_series
insured_person_document_number
insured_person_document_issue_date
insured_person_document_issuer_name
insured_person_registration_address
insured_person_phone
insured_person_email
card_insurance_agreement_number
card_insurance_agreement_sell_date
card_insurance_agreement_start_date
card_insurance_agreement_end_date
card_insurance_agreement_amount
card_insurance_agreement_bonus

String to sign

Signature