3.19. /api/v2/preauth-form

Введение

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

API URL

Примечание

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

Интеграционная среда	Производственная среда
https://sandbox.payneteasy.com/paynet/api/v2/preauth-form/ENDPOINTID	https://gate.payneteasy.com/paynet/api/v2/preauth-form/ENDPOINTID
https://sandbox.payneteasy.com/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID	https://gate.payneteasy.com/paynet/api/v2/preauth-form/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.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
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
first_name	Имя Плательщика.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
last_name	Фамилия Плательщика.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
state	Штат Плательщика. Для списка действительных кодов штатов см. Обязательные коды штатов. Требуется для США, Канады и Австралии.	`Необходимость`: Условно `Тип`: String `Длина`: 2
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
ssn	Последние четыре цифры номера социального страхования Плательщика.	`Необходимость`: Опционально `Тип`: Numeric `Длина`: 32
birthday	Дата рождения Плательщика в формате ГГГГММДД.	`Необходимость`: Опционально `Тип`: Numeric `Длина`: 8
cell_phone	Полный номер мобильного телефона Плательщика, включая код страны.	`Необходимость`: Опционально `Тип`: String `Длина`: 15
site_url	URL-адрес сайта электронной коммерции, откуда происходит платеж.	`Необходимость`: Опционально `Тип`: String `Длина`: 128
server_callback_url	URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны).Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся cтороны.Этот параметр может быть отправлен вместо notify_url. Если отправлен server_callback_url, Платёжный шлюз совершает обратный вызов только после получения финального статуса по изначальной транзакции. Если отправлен notify_url, Платёжный шлюз совершает обратный вызов после получения финального статуса по изначальной транзакции, а также по всем последующим событиям, связанным с этой транзакцией (возврат, принудительный возврат, и т.д.).	`Необходимость`: Опционально `Тип`: String `Длина`: 1024
notify_url	URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны).Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся cтороны.Этот параметр может быть отправлен вместо server_callback_url. Если отправлен server_callback_url, Платёжный шлюз совершает обратный вызов только после получения финального статуса по изначальной транзакции. Если отправлен notify_url, Платёжный шлюз совершает обратный вызов после получения финального статуса по изначальной транзакции, а также по всем последующим событиям, связанным с этой транзакцией (возврат, принудительный возврат, и т.д.).	`Необходимость`: Опционально `Тип`: String `Длина`: 1024
preferred_language	Двухбуквенный код языка Плательщика для многоязычных платежных форм.	`Необходимость`: Опционально `Тип`: String `Длина`: 2
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
preferred_language	Двухбуквенный код языка Плательщика для многоязычных платежных форм.	`Необходимость`: Опционально `Тип`: String `Длина`: 2
card_recurring_payment_id	Токенизированная платёжная информация держателя карты, также упоминающаяся как Идентификатор Повторного Платежа или Recurring Payment ID (RPI). Может быть создан с помощью запроса токенизации v4.	`Необходимость`: Условно `Тип`: Int
cardrefid	Ссылочный Идентификатор Платежа для последующих списаний. Может быть создан с помощью запроса токенизации v4 или запроса токенизации v2.	`Необходимость`: Условно `Тип`: Int

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

Примечание

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

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

Название параметра	Описание	Значение
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	Для транзакций в статусе error этот параметр будет содержать причину отклонения или сведения об ошибке.
error-code	Код ошибки для транзакций в статусе error.
redirect-url	URL-адрес страницы, на которую Присоединяющаяся сторона должна перенаправить браузер клиента методом HTTP 302.

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

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

client_orderid=902B4FF5
&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=69
&email=[email protected]
&currency=USD
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.com
&credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&purpose=user_account1
&redirect_url=http://sandbox.payneteasy.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2
&control=b7ba0b0ce36fda192c3772e045520c7a9cb5e442
&preferred_language=en

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

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: Thu, 13 Oct 2022 09:54:53 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-000002ddb0d3
&merchant-order-id=Test
&paynet-order-id=6863103
&redirect-url=https%3A%2F%2Fsandbox.payneteasy.com%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A68633370432F78675258396E6F78367975715973596936522B594B4F646168553D

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

HTTP/1.1 200 OK
Server: server
Date: Thu, 13 Oct 2022 09:58:28 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-000002ddb0d4
&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
notify_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