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

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

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

Для подписания запроса используется oauth авторизация.

API URLs

Интеграция	Боевая Среда
https://sandbox.goldenapple.com.cy/paynet/api/v2/card-insurance-document/ENDPOINTID	https://gate.goldenapple.com.cy/paynet/api/v2/card-insurance-document/ENDPOINTID

Данные запроса

Имя параметра запроса	Описание
client-order-id	Номер клиента в системе
order_id	Идентификатор заказа, назначенный в GoldenApple.

Для формирования запроса можно воспользоваться инструментом отладки. Формировать запрос требуется для родительской транзакции.

Для этого необходимо подставить имеющиеся данные для доступа к системе: endpoint_id (номер терминала в системе, по которому совершалась первая операция), consumer_key (логин торговца в системе) consumer_secret (контрольный ключ торговца) и заполнить остальные параметры запроса.

HTTP method
URL
parameters
version
consumer key
consumer secret
token
token secret
timestamp
nonce
signature method

normalized parameters

signature base string

signature

authorization header

Curl

Данные ответа

Имя параметра запроса	Описание
request_serial_number	Уникальный номер, назначенный сервером GoldenApple для конкретного запроса от торговца.
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-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в любом случае, независимо от того, будет ли транзакция одобрена или отклонена. Не следует использовать этот параметр для получения результатов со шлюза GoldenApple , так как все параметры проходят через браузер клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url	Обязательно, если отсутствуют оба параметра redirect_success_url и redirect_fail_url
redirect_success_url	1024/String	URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в случае, если транзакция одобрена. Не следует использовать этот параметр для получения результатов со шлюза GoldenApple , так как все параметры проходят через браузер клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется server_callback_url	Обязательно, если отсутствует параметр redirect_url
redirect_fail_url	1024/String	URL-адрес, на который будет перенаправлен держатель карты после завершения транзакции. Держатель карты будет перенаправлен в случае, если транзакция отклонена или отфильтрована. Не следует использовать этот параметр для получения результатов со шлюза GoldenApple , так как все параметры проходят через браузер клиента и могут быть потеряны во время передачи. Для доставки корректного результата платежа используется 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 protected]
&currency=AED
&ipaddress=65.153.12.232
&site_url=www.google.com
&purpose=user_account1
&redirect_url=https://doc.goldenapple.com.cy//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

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, который сервер GoldenApple возвращает для каждой созданной транзакции.

Адреса запроса статуса

На этапе интеграции предполагается использование тестовой среды sandbox.goldenapple.com.cy вместо производственной gate.goldenapple.com.cy.

Для интеграций торговца в одной валюте используется Endpoint ID, созданный для торговца в системе GoldenApple, и URL следующего формата: https://gate.goldenapple.com.cy/paynet/api/v2/status/ENDPOINTID Для мультивалютных интеграций торговца используется Endpoint group ID, созданный для торговца в системе GoldenApple, и URL следующего формата: https://gate.goldenapple.com.cy/paynet/api/v2/status/group/ENDPOINTGROUPID

Параметры запроса статуса

Параметр	Описание	Обязательность
login	Логин торговца в системе GoldenApple	Обязательность
client_orderid	Номер заказа в системе торговца, по которому запрашивается статус.	Обязательно
orderid	Номер заказа в системе GoldenApple	Обязательно
by-request-sn	Серийный номер API запроса в системе GoldenApple	Опционально
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 запроса торговца, присвоенный системой GoldenApple
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.goldenapple.com.cy/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 protected]
&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