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

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

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

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