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
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 |
Адрес электронной почты Плетельщика. |
Необходимость : ОбязательноТип : 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 |
Параметры запроса для страхования
Имя параметра
Описание
Свойства
insured_person_first_name
Имя страхователя.
Тип
: StringДлинна
: 256insured_person_last_name
Фамилия страхователя.
Тип
: StringДлинна
: 256insured_person_middle_name
Отчество страхователя.
Тип
: StringДлинна
: 256insured_person_birthday
Дата рождения страхователя.
Тип
: StringДлинна
: 256insured_person_document_series
Серия документа страхователя.
Тип
: StringДлинна
: 256insured_person_document_number
Номер документа страхователя.
Тип
: StringДлинна
: 256insured_person_document_issue_date
Дата выдачи документа страхователя.
Тип
: StringДлинна
: 256insured_person_document_issuer_name
Кем выдан документ страхователя.
Тип
: StringДлинна
: 256insured_person_document_issuer_code
Код подразделения отделения, выдавшего документ страхователя.
Тип
: StringДлинна
: 256insured_person_registration_address
Адрес регистрации страхователя.
Тип
: StringДлинна
: 256insured_person_phone
Полный международный номер телефона страхователя.
Тип
: StringДлинна
: 256insured_person_email
Адрес электронной почты страхователя.
Тип
: StringДлинна
: 256card_insurance_agreement_number
Номер договора.
Тип
: StringДлинна
: 256card_insurance_agreement_sell_date
Дата продажи.
Тип
: StringДлинна
: 256card_insurance_agreement_start_date
Дата начала договора.
Тип
: StringДлинна
: 256card_insurance_agreement_end_date
Дата окончания договора.
Тип
: StringДлинна
: 256card_insurance_agreement_amount
Сумма страхования.
Тип
: StringДлинна
: 256card_insurance_agreement_bonus
Премия страхования.
Тип
: StringДлинна
: 256
Параметры ответа
Note
Название параметра |
Описание |
---|---|
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Длинна
: 128order_desc
Описание заказа.
Необходимость
: ОбязательноТип
: StringДлинна
: 64kfirst_name
Имя Клиента.
Необходимость
: ОбязательноТип
: StringДлинна
: 50last_name
Фамилия клиента.
Необходимость
: ОбязательноТип
: StringДлинна
: 50ssn
Последние четыре цифры номера социального страхования Клиента.
Необходимость
: ОпциональноТип
: NumericДлинна
: 4birthday
Дата рождения Клиента в формате ГГГГMMДД.
Необходимость
: ОпциональноТип
: NumericДлинна
: 8address1
Адрес Клиента срока 1.
Необходимость
: ОбязательноТип
: StringДлинна
: 50city
Город Клиента.
Необходимость
: ОбязательноТип
: StringДлинна
: 50state
Штат Клиента. Для списка действительных кодов штатов см. Обязательные коды штатов. Требуется для США, Канады и Австралии.
Необходимость
: Зависит от Банк-ЭквайераТип
: StringДлинна
: 2zip_code
Почтовый индекс Клиента.
Необходимость
: ОбязательноТип
: StringДлинна
: 10country
Страна Плательщика. Для списка действительных кодов см. Коды стран.
Необходимость
: ОбязательноТип
: StringДлинна
: 2phone
Полный международный номер телефона Клиента, включая код страны.
Необходимость
: ОбязательноТип
: StringДлинна
: 15cell_phone
Полный номер мобильного телефона Клиента, включая код страны.
Необходимость
: ОпциональноТип
: StringДлинна
: 15Адрес электронной почты Клиента.
Необходимость
: ОбязательноТип
: StringДлинна
: 50purpose
Назначение, куда направляется оплата.
Необходимость
: ОпциональноТип
: StringДлинна
: 128amount
Сумма к списанию. Сумма должна быть указана в минимальных единицах с . разделителем. 100.5 в RUB означает 100 российских рублей и 50 копеек.
Необходимость
: ОбязательноТип
: NumericДлинна
: 10insurance_amount
Сумма к страхованию. Сумма должна быть указана в минимальных единицах с . разделителем. 100.5 в RUB означает 100 российских рублей и 50 копеек.
Необходимость
: ОбязательноТип
: NumericДлинна
: 10currency
Валюта, в которой проводится операция (трехбуквенный код валюты). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля.
Необходимость
: ОбязательноТип
: StringДлинна
: 3ipaddress
IP-адрес Клиента.
Необходимость
: ОбязательноТип
: StringДлинна
: 45site_url
URL-адрес сайта, с которого выполнен запрос.
Необходимость
: ОпциональноТип
: StringДлинна
: 128control
Контрольная сумма. Представляет собой SHA-1 свёртку от конкатенации следующих параметров: ENDPOINTID/GROUPID + client_orderid + amount (в копейках) + email + merchant-control.
Необходимость
: ОбязательноТип
: StringДлинна
: 40redirect_url
URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в любом случае, независимо от того, будет ли транзакция одобрена или отклонена. Не следует использовать этот параметр для получения результатов со шлюза Payneteasy , так как все параметры проходят через браузер Клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url.
Необходимость
: Обязательно, если отсутствуют оба параметра redirect_success_url и redirect_fail_urlТип
: StringДлинна
: 1024redirect_success_url
URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в случае, если транзакция одобрена. Не следует использовать этот параметр для получения результатов со шлюза Payneteasy , так как все параметры проходят через браузер Клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url.
Необходимость
: Обязательно, если отсутствует параметр redirect_urlТип
: StringДлинна
: 1024redirect_fail_url
URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в случае, если транзакция отклонена или отфильтрована. Не следует использовать этот параметр для получения результатов со шлюза Payneteasy , так как все параметры проходят через браузер Клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url.
Необходимость
: Обязательно, если отсутствует параметр redirect_urlТип
: StringДлинна
: 1024server_callback_url
URL-адрес, по которому будет отправлен результат транзакции. Торговец может использовать этот URL для индивидуальной обработки завершения транзакции, например, для сбора данных о продажах в базе данных. Больше информации: Обратный вызов Присоединяющейся Стороны.
Необходимость
: ОпциональноТип
: StringДлинна
: 1024preferred_language
Двубуквенный код языка Клиента, используется для мультиязычных платежных форм.
Необходимость
: ОпциональноТип
: StringДлинна
: 2merchant_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
¤cy=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 ¤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 &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
Конструктор запроса
String to sign |
---|
Signature |
---|
|