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 |
Параметры запроса оплаты с использованием формы
Примечание
Предупреждение
Следующие символы должны быть экранированы в значениях параметров: & + «.
Название параметра |
Описание |
Значение |
---|---|---|
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-адрес, на который будет перенаправлен Плательщик после завершения транзакции. Перенаправление выполняется в любом случае, независимо от того, получила ли транзакция успешный, неуспешный или любой другой конечный статус (см. Статусы транзакций).
Не следует использовать параметры, отправленные вместе с 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 |
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.
This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc).
|
Необходимость : ОпциональноТип : StringДлина : 1024 |
notify_url |
URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции.
Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны).Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся cтороны.Этот параметр может быть отправлен вместо server_callback_url. Если отправлен server_callback_url, Платёжный шлюз совершает обратный вызов только после получения финального статуса по изначальной транзакции. Если отправлен notify_url, Платёжный шлюз совершает обратный вызов после получения финального статуса по изначальной транзакции, а также по всем последующим событиям, связанным с этой транзакцией (возврат, принудительный возврат, и т.д.).
|
Необходимость : ОпциональноТип : StringДлина : 1024 |
preferred_language |
Двухбуквенный код языка Плательщика для многоязычных платежных форм. |
Необходимость : ОпциональноТип : StringДлина : 2 |
order_desc |
Дополнительные сведения о транзакции для Присоединяющейся Стороны, которые можно прикрепить к транзакции и получить обратно в ответе на запрос статуса или обратном вызове. Может содержать данные, которые будут полезны во внешней системе Присоединяющейся Стороны, например VIP клиент, телевизионная промо-кампания.
Information returns in Status response and Connecting Party Callback.
|
Необходимость : ОпциональноТип : StringДлина : 64k |
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 |
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 |
Для транзакций в статусе declined или error этот параметр будет содержать причину отклонения или сведения об ошибке. |
error-code |
Код ошибки для транзакций в статусе declined или error. |
redirect-url |
URL-адрес страницы, на которую Присоединяющаяся сторона должна перенаправить браузер клиента методом HTTP 302. |
Пример запроса
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=[email protected]
¤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
Пример запроса со страхованием
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: 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
Пример неуспешного ответа
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 |
---|
|