3.22. /api/v2/sale-form

Введение

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

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

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

Note

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

Warning

The following characters must be escaped in the parameter values: & + .

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

Описание

Значение

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, where the Payer is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is approved, declined in any other final status.
Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Pass http://https://doc.payneteasy.com if you have no need to return payer anywhere. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both.
Необходимость: Опционально
Тип: String
Длина: 1024

redirect_success_url

URL-адрес, на который будет перенаправлен Плательщик после получения успешного статуса транзакции.(cм. Статусы транзакций).
Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Otherwise put http://https://doc.payneteasy.com if there is no need to redirect Payer anywhere. Use either combination of redirect_success_url and redirect_fail_url or redirect_url, not both.
Необходимость: Опционально
Тип: String
Длина: 1024

redirect_fail_url

URL-адрес, на который будет перенаправлен Плательщик после получения неуспешного статуса транзакции.(cм. Статусы транзакций).
Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Pass http://https://doc.payneteasy.com if there is no need to redirect Payer anywhere. Use either combination of redirect_fail_url and redirect_success_url or redirect_url, not both.
Необходимость: Опционально
Тип: 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.
Необходимость: Опционально
Тип: 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 в режиме PNE.

Необходимость: Опционально
Тип: Int
Длина: 10

merchant_customer_identifier

Идентификатор клиента-продавца в системе CMS. Параметр становится обязательным, если включена система CMS в режиме CRM.

Необходимость: Опционально
Тип: Varchar
Длина: 64

client_orderid

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

Необходимость: Условно
Тип: Int

client_orderid

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

Необходимость: Условно
Тип: Int
For Faster Payments System (СБП) integration use purpose field for fpsRequestId parameter.

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

Существует возможность передавать значения полей по API для предварительного заполнения формы страхования.

Имя параметра

Описание

Свойства

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

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

Note

Ответ имеет заголовок 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.

Параметры платежной формы для страхования

Note

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

Имя параметра

Описание

Свойства

client_orderid

Идентификатор заказа в системе торговца.

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

order_desc

Описание заказа.

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

first_name

Имя Клиента.

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

last_name

Фамилия клиента.

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

ssn

Последние четыре цифры номера социального страхования Клиента.

Необходимость: Опционально
Тип: Numeric
Длинна: 4

birthday

Дата рождения Клиента в формате ГГГГMMДД.

Необходимость: Опционально
Тип: 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

Назначение, куда направляется оплата.

Необходимость: Опционально
Тип: String
Длинна: 128

amount

Сумма к списанию. Сумма должна быть указана в минимальных единицах с . разделителем. 100.5 в RUB означает 100 российских рублей и 50 копеек.

Необходимость: Обязательно
Тип: Numeric
Длинна: 10

insurance_amount

Сумма к страхованию. Сумма должна быть указана в минимальных единицах с . разделителем. 100.5 в RUB означает 100 российских рублей и 50 копеек.

Необходимость: Обязательно
Тип: Numeric
Длинна: 10

currency

Валюта, в которой проводится операция (трехбуквенный код валюты). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля.

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

ipaddress

IP-адрес Клиента.

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

site_url

URL-адрес сайта, с которого выполнен запрос.

Необходимость: Опционально
Тип: String
Длинна: 128

control

Контрольная сумма. Представляет собой SHA-1 свёртку от конкатенации следующих параметров: ENDPOINTID/GROUPID + client_orderid + amount (в копейках) + email + merchant-control.

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

redirect_url

URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в любом случае, независимо от того, будет ли транзакция одобрена или отклонена. Не следует использовать этот параметр для получения результатов со шлюза Payneteasy , так как все параметры проходят через браузер Клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url.

Необходимость: Обязательно, если отсутствуют оба параметра redirect_success_url и redirect_fail_url
Тип: String
Длинна: 1024

redirect_success_url

URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в случае, если транзакция одобрена. Не следует использовать этот параметр для получения результатов со шлюза Payneteasy , так как все параметры проходят через браузер Клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url.

Необходимость: Обязательно, если отсутствует параметр redirect_url
Тип: String
Длинна: 1024

redirect_fail_url

URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в случае, если транзакция отклонена или отфильтрована. Не следует использовать этот параметр для получения результатов со шлюза Payneteasy , так как все параметры проходят через браузер Клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url.

Необходимость: Обязательно, если отсутствует параметр redirect_url
Тип: String
Длинна: 1024

server_callback_url

URL-адрес, по которому будет отправлен результат транзакции. Торговец может использовать этот URL для индивидуальной обработки завершения транзакции, например, для сбора данных о продажах в базе данных. Больше информации: Обратный вызов Присоединяющейся Стороны.

Необходимость: Опционально
Тип: String
Длинна: 1024

preferred_language

Двубуквенный код языка Клиента, используется для мультиязычных платежных форм.

Необходимость: Опционально
Тип: String
Длинна: 2

merchant_form_data

Параметры, отправленные в merchant_form_data, создают на платежной форме макросы с теми же именами и переданными значениями, которые можно затем использовать для изменения логики работы формы или отображения дополнительных данных (например, переключение между светлым и темным режимом). Значение - строка с параметрами, разделенными символом &, закодированная методом percent URL encode, пример: значение :ex:testparam%3Dtest1%26mynewparam%3Dtest2 будет преобразовано в макросы на форме: :ex:$MFD_testparam = test1 и :ex:$MFD_mynewparam = test2. В названиях параметров допускаются символы [a-zA-Z0-9], в значениях допускаются символы [a-zA-Z0-9], контрольные символы [=&], максимальный размер 2MB. Например, этот параметр можно использовать для отображения формы оплаты в светлом/темном режиме в зависимости от значения, переданного соединяющейся стороной (например, передайте в запросе merchant_form_data=theme%3Ddark, а заполнитель макроса $MFD_theme в форме оплаты будет изменен на темный.

Необходимость: Опционально
Тип: String
Длинна: 128

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

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=john.smith@gmail.com
&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

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

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

Пример успешного запроса для страхования

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=10.42
&insurance_amount=10
&email=john.smith@gmail.com
&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
&insured_person_email=john.smith@gmail.com
&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: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

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

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

String to sign
Signature