3.25. /api/v2/card-insurance-document

Формирование запроса

После успешного проведения транзакции, необходимо сформировать запрос для скачивания полиса страхования с данными клиента в формате PDF.
Для подписания запроса используется oauth авторизация.

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.

Для формирования запроса можно воспользоваться инструментом отладки. Формировать запрос требуется для родительской транзакции.
Для этого необходимо подставить имеющиеся данные для доступа к системе: endpoint_id (номер терминала в системе, по которому совершалась первая операция), consumer_key (логин торговца в системе) consumer_secret (контрольный ключ торговца) и заполнить остальные параметры запроса.
HTTP method
URL
parameters
version
consumer key
consumer secret
timestamp
nonce
signature method

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

Полный номер мобильного телефона клиента, включая код страны.

Опционально

email

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
&currency=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

Отладка платежной формы

Также возможен сценарий когда управление процессом списания страховой суммы передаётся на сторону мерчанта и осуществляется без отображения информации на платёжной форме через рекуррентный запрос с использованием card-ref-id карты.

Отладка рекуррентного запроса

Страхование при переводе средств

Для осуществления операции страхования при переводе средств на предоставленном End point должно быть разрешено проведение соответствующей операции, помимо этого в самом запросе обязательно нужно указать параметр insurance_amount. Обратите внимание, что страховой полис при этом не формируется и не показывается: при получении запроса на перевод средств операция сразу начинает обрабатываться.

Отладка переводов

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.

URL Вместо ENDPOINTID используйте ID нужного Endpoint в системе
login your login should be used as Consumer Public for OAuth
client_orderid make it or use your internal invoice ID
destination-card-no enter the beginning of the sequence, and then "i".
destination-card-ref-id
destination-iban-no
destination-bic
order_desc
amount
insurance_amount
currency
ipaddress
first_name
middle_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
email
purpose
receiver_first_name
receiver_middle_name
receiver_last_name
receiver_phone
receiver_resident
receiver_identity_document_series
receiver_identity_document_number
receiver_identity_document_id
receiver_address1
receiver_city
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data

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
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.

Выполнение запроса статуса

Торговцу необходимо использовать запрос статуса по 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 для большей информации.

email

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

Отладка запроса статуса

endpointid or groupid

input ENDPOINTID or ENDPOINTGROUPID

login

input Login

client_orderid

input Invoice Number

orderid
merchant_control

input Control Key

by-request-sn

String to sign
Signature