3.22. /api/v2/sale-form

Введение

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

API URL

Примечание

Путь 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

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

Примечание

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

Предупреждение

Следующие символы должны быть экранированы в значениях параметров: & + «.

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

Описание

Значение

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-адрес, на который будет перенаправлен Плательщик после завершения транзакции. Перенаправление выполняется в любом случае, независимо от того, получила ли транзакция успешный, неуспешный или любой другой конечный статус (см. Статусы транзакций).
Не следует использовать параметры, отправленные вместе с 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-адрес, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны).Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся cтороны. Данный параметр может быть передан вместо notify_url. При использовании server_callback_url платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. При использовании notify_url платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.)
Необходимость: Опционально
Тип: String
Длина: 1024

notify_url
URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны).Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся cтороны. Данный параметр может быть передан вместо server_callback_url. При использовании notify_url платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). При использовании server_callback_url платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции.
Необходимость: Опционально
Тип: String
Длина: 1024

preferred_language

Двухбуквенный код языка Плательщика для многоязычных платежных форм.
Необходимость: Опционально
Тип: String
Длина: 2

order_desc
Дополнительные сведения о транзакции для Присоединяющейся Стороны, которые можно прикрепить к транзакции и получить обратно в ответе на запрос статуса или обратном вызове. Может содержать данные, которые будут полезны во внешней системе Присоединяющейся Стороны, например VIP клиент, телевизионная промо-кампания.
Информация возвращается в ответе статуса и в колбэках Присоединяющейся Стороны
Необходимость: Опционально
Тип: 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
Для интеграции Системы Быстрых Платежей (СБП) используйте ячейку purpose для параметра fpsRequestId

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

Примечание

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

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

Описание

Значение

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

Для транзакций в статусе declined или error этот параметр будет содержать причину отклонения или сведения об ошибке.

error-code

Код ошибки для транзакций в статусе declined или error.

redirect-url

URL-адрес страницы, на которую Присоединяющаяся сторона должна перенаправить браузер клиента методом HTTP 302. Подробнее см. General Payment-form Process Flow.

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

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

Пример запроса со страхованием

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: 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

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

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