3.19. /api/v2/preauth-form
Введение
Предавторизация по форме инициируется через запрос методом HTTPS POST на указанный ниже URL с использованием указанных параметров. Для аутентификации запроса используется SHA-1. См. Статусы транзакций.
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 |
Параметры запроса
Примечание
Название параметра |
Описание |
Значение |
---|---|---|
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> (см: 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 |
Параметры ответа
Примечание
Параметры ответа |
Описание |
---|---|
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 |
The error code is case of error status. |
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]
¤cy=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]
¤cy=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
Конструктор запроса
String to sign |
---|
Signature |
---|
|