3.25. /api/v2/card-insurance-document
Формирование запроса
API URLs
Интеграция |
Боевая Среда |
---|---|
https://sandbox.payneteasy.eu/paynet/api/v2/card-insurance-document/ENDPOINTID |
https://gate.payneteasy.eu/paynet/api/v2/card-insurance-document/ENDPOINTID |
Данные запроса
Имя параметра запроса |
Описание |
---|---|
client-order-id |
Номер клиента в системе |
order_id |
Идентификатор заказа, назначенный в Payneteasy. |
normalized parameters |
---|
signature base string |
---|
signature |
---|
authorization header |
---|
Curl |
---|
|
Данные ответа
Имя параметра запроса |
Описание |
---|---|
request_serial_number |
Уникальный номер, назначенный сервером Payneteasy для конкретного запроса от торговца. |
document_path |
Ссылка для скачивания документа |
Пример ответа:
{
"request_serial_number": "00000000-0000-0000-0000-000001fd4472",
"document_path": "https://sandbox.sbctech.ru/paynet/api/v2/download/card-ins-95255434629222889419"
}
Полученную в ответе ссылку необходимо отобразить в браузере клиента.
Файл доступен только для одной загрузки.
Передача полей по API
Существует возможность передавать значения полей по 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 |
Страховая премия |
Параметры платежной формы
Параметры запроса |
Длина/Тип |
Описание |
Обязательность* |
---|---|---|---|
client_orderid |
128/String |
Идентификатор заказа в системе торговца. |
Обязательно |
order_desc |
64k/String |
Описание заказа. |
Обязательно |
first_name |
50/String |
Имя клиента. |
Обязательно |
last_name |
50/String |
Фамилия клиента. |
Обязательно |
ssn |
4/Numeric |
Последние четыре цифры номера социального страхования клиента. |
Опционально |
birthday |
8/Numeric |
Дата рождения клиента в формате ГГГГMMДД. |
Опционально |
address1 |
50/String |
Адрес клиента срока 1. |
Обязательно |
city |
50/String |
Город клиента. |
Обязательно |
state |
2/String |
Штат покупателя (Двухбуквенные коды штатов). Смотри country_state_codes список кодов штатов. Обязательно для США, Канады и Австралии. |
Зависит от Банк-Эквайера |
zip_code |
10/String |
Почтовый индекс клиента. |
Обязательно |
country |
2/String |
Страна клиента (Двухбуквенные коды стран). Смотри country_state_codes список кодов стран. |
Обязательно |
phone |
15/String |
Полный международный номер телефона клиента, включая код страны. |
Обязательно |
cell_phone |
15/String |
Полный номер мобильного телефона клиента, включая код страны. |
Опционально |
50/String |
Адрес электронной почты клиента. |
Обязательно |
|
purpose |
128/String |
Назначение, куда направляется оплата. |
Опционально |
amount |
10/Numeric |
Сумма к списанию. Сумма должна быть указана в минимальных единицах с . разделителем. 100.5 в RUB означает 100 российских рублей и 50 копеек. |
Обязательно |
insurance_amount |
10/Numeric |
Сумма к страхованию. Сумма должна быть указана в минимальных единицах с . разделителем. 100.5 в RUB означает 100 российских рублей и 50 копеек. |
Обязательно |
currency |
3/String |
Валюта, в которой проводится операция (трехбуквенный код валюты). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля. |
Обязательно |
ipaddress |
45/String |
IP-адрес клиента. |
Обязательно |
site_url |
128/String |
URL-адрес сайта, с которого выполнен запрос. |
Опционально |
control |
40/String |
Контрольная сумма. Представляет собой SHA-1 свёртку от конкатенации следующих параметров: ENDPOINTID/GROUPID + client_orderid + amount (в копейках) + email + merchant-control. |
Обязательно |
redirect_url |
1024/String |
URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в любом случае, независимо от того, будет ли транзакция одобрена или отклонена. Не следует использовать этот параметр для получения результатов со шлюза Payneteasy , так как все параметры проходят через браузер клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url |
Обязательно, если отсутствуют оба параметра redirect_success_url и redirect_fail_url |
redirect_success_url |
1024/String |
URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в случае, если транзакция одобрена. Не следует использовать этот параметр для получения результатов со шлюза Payneteasy , так как все параметры проходят через браузер клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url |
Обязательно, если отсутствует параметр redirect_url |
redirect_fail_url |
1024/String |
URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в случае, если транзакция отклонена или отфильтрована. Не следует использовать этот параметр для получения результатов со шлюза Payneteasy , так как все параметры проходят через браузер клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url |
Обязательно, если отсутствует параметр redirect_url |
server_callback_url |
1024/String |
URL-адрес, по которому будет отправлен результат транзакции. Торговец может использовать этот URL для индивидуальной обработки завершения транзакции, например, для сбора данных о продажах в базе данных. Больше информации: Connecting Party Callbacks |
Опционально |
preferred_language |
2/String |
Двубуквенный код языка лиента, используется для мультиязычных платежных форм |
Опционально |
merchant_form_data |
128/String |
Параметры, отправленные в 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 в форме оплаты будет изменен на темный. |
Опционально |
Пример запроса
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=john.smith@gmail.com
¤cy=AED
&ipaddress=65.153.12.232
&site_url=www.google.com
&purpose=user_account1
&redirect_url=https://doc.payneteasy.eu/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
Success Response Example
Fail Response Example
Postman Collection
Request Builder
Отладка платежной формы
Отладка рекуррентного запроса
Страхование при переводе средств
Отладка переводов
Enter your private key in PKCS#1 container to use debug. See rsasha256 for details.
Fillup mandatory fields (the red ones) with appropriate values. Empty values will not be included in output.
Use either destination-card-no, destination-card-ref-id or destination-iban-no with destination-bic.
Normalized parameters string to sign, according to OAuth 1.0a rules |
---|
POST body parameters to submit |
---|
OAuth 1.0a headers to submit. |
---|
HEX Encoded Signature |
---|
Base64 Encoded Signature |
---|
|
Выполнение запроса статуса
Торговцу необходимо использовать запрос статуса по API для получения актуальной информации о статусе проведения транзакции. Запрос статуса осуществляется по параметру order_id, который сервер Payneteasy возвращает для каждой созданной транзакции.
Адреса запроса статуса
На этапе интеграции предполагается использование тестовой среды sandbox.payneteasy.eu вместо производственной gate.payneteasy.eu.
Для интеграций торговца в одной валюте используется Endpoint ID, созданный для торговца в системе Payneteasy, и URL следующего формата: https://gate.payneteasy.eu/paynet/api/v2/status/ENDPOINTID Для мультивалютных интеграций торговца используется Endpoint group ID, созданный для торговца в системе Payneteasy, и URL следующего формата: https://gate.payneteasy.eu/paynet/api/v2/status/group/ENDPOINTGROUPID
Параметры запроса статуса
Параметр |
Описание |
Обязательность |
---|---|---|
login |
Логин торговца в системе Payneteasy |
Обязательность |
client_orderid |
Номер заказа в системе торговца, по которому запрашивается статус. |
Обязательно |
orderid |
Номер заказа в системе Payneteasy |
Обязательно |
by-request-sn |
Серийный номер API запроса в системе Payneteasy |
Опционально |
control |
Контрольная сумма, подтверждающая отправление запроса торговцем. Представляет собой SHA-1 свёртку от конкатенации следующих параметров: login + client-order-id + paynet-order-id + merchant-control |
Обязательно |
Параметры ответа на запрос статуса
Параметр |
Описание |
---|---|
type |
Тип ответа, ожидаемое значение: status-response |
status |
Статус заказа. Возможные значения: Status List |
amount |
Сумма заказа. Это значение может быть изменено во время транзакции. |
paynet-order-id |
Номер заказа, присвоенный системой QA |
merchant-order-id |
Номер заказа в системе торговца. |
phone |
Телефон покупателя. |
html |
HTML код страницы 3-D Secure, закодированный в формат MIME application/x-www-form-urlencoded. Торговцу необходимо декодировать этот параметр перед показом формы покупателю. Система QA HTML код страницы 3-D Secure, закодированный в формат MIME application/x-www-form-urlencoded. Торговцу необходимо декодировать этот параметр перед показом формы покупателю. Система Payneteasy возвращает этот параметр в ответе, когда получает форму 3-D Secure. Параметр содержит HTML код страницы, который должен быть передан в интернет-браузер клиента без изменений. Для non-3DS транзакций данный параметр не присутствует в ответе. Также этот параметр не присутствует в ответе при запросе статуса транзакции по форме (sale form, transfer form). |
redirect-to |
Параметр может использоваться вместо параметра html Содержит URL для переадресации клиента на форму 3-D Secure. Торговец должен использовать метод GET для переадресации клиента. Для non-3DS транзакций данный параметр не присутствует в ответе. Также этот параметр не присутствует в ответе при запросе статуса транзакции по форме (sale form, transfer form). |
serial-number |
Уникальный номер конкретного API запроса торговца, присвоенный системой Payneteasy |
last-four-digits |
Последние четыре цифры номера карты покупателя. |
bin |
Банковский идентификационный номер (БИН) карты покупателя. |
card-type |
Тип карты покупателя (например VISA, MASTERCARD, MIR). |
gate-partial-reversal |
Поддерживаются ли частичные возвраты на шлюзе (enabled or disabled). |
gate-partial-capture |
Поддерживаются ли частичные capture на шлюзе (enabled или disabled). |
transaction-type |
Тип транзакции (sale, reversal, capture, preauth). |
processor-rrn |
Регистрационный номер транзакции в системе банка-эквайера (RRN). |
processor-tx-id |
Идентификатор транзакции в системе банка-эквайера. |
receipt-id |
Ссылка на электронный чек https://gate.payneteasy.eu/paynet/view-receipt/ENDPOINTID/receipt-id/ |
name |
Имя. |
cardholder-name |
Имя держателя карты. |
card-exp-month |
Последний месяц действия карты. |
card-exp-year |
Последний год действия карты. |
card-hash-id |
Уникальный идентификатор карты используется для программы лояльности или проверок на fraud. |
card-country-alpha-three-code |
Трехбуквенный код страны эмитента карты отправителя. Смотри card-country-codes для большей информации. |
E-mail покупателя. |
|
purpose |
Назначение, куда направляется оплата. |
bank-name |
Название банка-эмитента. |
terminal-id |
Идентификатор терминала банка-эквайера. |
paynet-processing-date |
Дата процессинга транзакции в системе банка-эквайера. |
approval-code |
Код подтверждения банка-эквайера. |
order-stage |
Стадия процессинга транзакции. Смотри Order Stage для большей информации |
loyalty-balance |
Текущий бонусный баланс программы лояльности для данной операции. if available |
loyalty-message |
Сообщение от программы лояльности. if available |
loyalty-bonus |
Бонусное значение программы лояльности для данной операции. if available |
loyalty-program |
Название программы лояльности для данной операции. if available |
descriptor |
Идентификатор банка. |
error-message |
Если статус заказа declined, error или filtered этот параметр содержит причину отказа. |
error-code |
Код ошибки для заказов в статусе declined, error, filtered. |
by-request-sn |
Серийный номер запроса, если он содержится в параметрах запроса. |
verified-3d-status |
Статус результата 3-D Secure. Смотри 3D Secure Status List для большей информации. |
verified-rsc-status |
Смотри Random Sum Check Status List для большей информации. |
merchantdata |
Если представлен в инициализирующем запросе, merchant_data параметр и его значение будут включены в ответе на запрос статуса. |
initial-amount |
Сумма, назначенная в инициализирующей транзакции, без каких-либо комиссий. Это значение может не быть изменено во время транзакции. |
Пример ответа на запрос статуса
type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5044
&merchant-order-id=902B4FF5
&processor-tx-id=PNTEST-159884
&paynet-order-id=159884
&status=approved
&amount=10.42
&descriptor=test-usd
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=sale
&receipt-id=a5061379-6ff5-3565-a9ba-1b8a814d04f6
&name=TEST HOLDER
&cardholder-name=TEST HOLDER
&card-exp-month=1
&card-exp-year=2016
&email=john.smith@gmail.com
&processor-rrn=510321889824
&approval-code=242805
&order-stage=sale_approved
&last-four-digits=9001
&bin=520306
&card-type=MASTERCARD
&phone=12063582043
&bank-name=CITIBANK
&paynet-processing-date=2015-04-09 17:14:26 MSK
&by-request-sn=00000000-0000-0000-0000-0000005b2a8a
&card-hash-id=1493114
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED
&merchantdata=promo
Пример формирования подписи запроса
Контрольная сумма подтверждает отправку запроса статуса торговцем. Параметр merchant_control известен только торговцу и должен быть защищён от доступа третьих лиц. Контрольная сумма представляет собой SHA-1 свёртку от конкатенации следующих параметров:
login
client_orderid
orderid
merchant_control
Пример расчёта контрольной суммы:
Parameter Name |
Parameter Value |
---|---|
login |
cool_merchant |
client_orderid |
5624444333322221111110 |
orderid |
9625 |
merchant_control |
r45a019070772d1c4c2b503bbdc0fa22 |
Строка для формирования контрольной суммы будет выглядеть следующим образом:
cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22
Шифрование вышеприведённой строки с помощью алгоритма SHA-1 . приводит к следующему значению контрольной суммы:
c52cfb609f20a3677eb280cc4709278ea8f7024c
Отладка запроса статуса
String to sign |
---|
Signature |
---|
|