Web
Операция покупки через Apple Pay
Для интеграции кнопки Apple Pay на платежную страницу интернет магазина необходимо реализовать метод ApplePaySession.canMakePaymentsWithActiveCard, этот метод определяет поддерживает ли данное устройство оплату с помощью Apple Pay.
Если поддерживает оплата - необходимо отрисовать кнопку “Купить с помощью Apple Pay”.
Далее необходимо создать объект ApplePaySession , с параметрами покупки:
countryCode: 'UA',
currencyCode: 'UAH',
supportedNetworks: ['visa', 'masterCard'],
merchantCapabilities: ['supports3DS'],
total: { label: 'Your Merchant Name', amount: '10.00' },
Описание полей можно посмотреть в документации Apple Pay on Web.
На событие onvalidatemerchant необходимо повесить обработчик, в котором будет вызываться API “api/apple/validate” . Описание метода будет ниже.
На событие onpaymentauthorized необходимо повесить обработчик, который будет вызывать API “api/apple/payment”.
После подтверждения платежа в onpaymentauthorized необходимо вызвать метод
ApplePaySession.completePayment.
Документацию по ApplePaySession можно найти на оф сайте Apple (https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api).
Валидация мерчанта Apple Pay (api/apple/validate).
Production url: https://pay.concord.ua/api/apple/validate
POST параметры:
| Параметр | Описание | Значение |
|---|---|---|
| operation | Тип операции | Purchase |
| apple_validation_url | Данный параметр приходит в событии onvalidatemerchant, event.validationURL | |
| Пример: | ||
| session.onvalidatemerchant = (event) => { | ||
| console.log(event.validationURL); | ||
| } | ||
| merchant_id | ID мерчанта, выдается поцесcингом | |
| amount | Сумма операции. Пример 500.00 | |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,order_id,amount,currency_iso,description разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! | ||
| order_id | Уникальный номер операции на стороне торговца. Если операция дублируется - торговец получает ошибку. | |
| currency_iso | Валюта платежа. | UAH |
| description | Назначение платежа. Выводится на платежной странице, при вводе платежных реквизитов. Отображается в выписке по счету и реестрах | |
| add_params | Массив с дополнительными параметрами. Дополнительные параметры потом возвращаются мерчанту в callback вызове | |
| callback_url | URL на который придет информация о результате выполнения платежа |
Для операции по протоколу 3DS2 в add_params необходимо передать следующие параметры:
| Параметр | Обазятаельность | Значение |
| AReqDetails.OrderID | Да | Идентификатор заказа, по которому необходимо выполнить операцию |
| AReqDetails.browserAcceptHeader | Да | Содержимое HTTP-заголовков браузера покупателя. Максимальное значение – 2048 символов |
| AReqDetails.browserColorDepth | Да | Значение, представляющее битовую глубину цветовой палитры для отображения изображений, в битах на пиксель. Максимальное значение – 2 символа.
Возможные значения: 1 - 1 бит; 4 - 4 бита; 8 - 8 битов; 15 - 15 битов; 16 - 16 битов; 24 - 24 бита; 32 - 32 бита; 48 - 48 битов |
| AReqDetails.browserIP | Да | IP-адрес браузера. Возможные форматы значения:
IPv4-адрес указан в виде четырех групп чисел в десятичной системе счисления, разделенных символом «.». Например: 100.12.123.255. IPv6-адрес указан в виде восьми групп чисел в шестнадцатеричной системе счисления, разделенных символом «:». Например: 2011: 0db8: 85a3: 0101: 0101: 8a2e: 0370: 7334 |
| AReqDetails.browserLanguage | Да | Язык браузера, указанный в IETF BCP47. Максимальное значение – 8 символов |
| AReqDetails.browserScreenHeight | Да | Общая высота (в пикселях) экрана, отображаемого держателю карты. Максимальное значение – 6 символов |
| AReqDetails.browserScreenWidth | Да | Общая ширина (в пикселях) экрана, отображаемого держателю карты. Максимальное значение – 6 символов |
| ReqDetails.browserTZ | Да | Разница во времени между временем по UTC и местным временем браузера пользователя. Максимальное значение – 5 символов |
| AReqDetails.browserUserAgent | Да | Содержимое HTTP-заголовка User-Agent. Максимальное значение – 2048 символов |
| AReqDetails.browserJavaEnabled | Да | Признак возможности выполнения JavaScript в браузере держателя карты. Возможные значения: true false |
| AReqDetails.threeRIInd | Да | Тип запроса, который выполняет ТСП без участия держателя карты (рекуррентные платежи). Возможные значения:
01 (периодический платеж/перевод); 02 (частичная оплата); 03 (добавление карты); 04 (сохранение информации о карте); 05 (идентификация учетной записи); 80-99 (значения зарезервированные для использования DS) |
| AReqDetails.notificationUrl | Да | URL-адрес сервис провайдера, на который возвращается POST-сообщение CRes от ACS, после выполнения проверки владельца карты при challenge-flow. |
| AReqDetails.deviceChannel | Да | Тип устройства, с которого инициирована транзакция. Возможные значения:
01 - мобильное приложение ТСП (App-based); 02 - браузер пользователя(Browser); 03 - интернет-магазин (3DS Requestor) На данный момент доступно только значение: 02 - браузер пользователя(Browser). |
| CReqDetails.WindowWidth | Да | Ширина окна браузера (в пикселях), в котором отображаются страницы сайта ТСП |
| CReqDetails.WindowHeight | Да | Высота окна браузера (в пикселях), в котором отображаются страницы сайта ТСП |
В ответ приходят следующие параметры:
| Параметр | Описание |
|---|---|
| apple_validate_data | Данные которые необходимо передать в метод session.completeMerchantValidation |
| order_key | Идентификатор заказа в платежной системе |
| code | Код ответа если 0 - все ок |
| message | Расшифровка кода ответа |
Подтверждение платежа Apple Pay (api/apple/payment)
Production url: https://pay.concord.ua/api/apple/payment
POST параметры:
| Название | Описание |
|---|---|
| order_key | Идентификатор заказа в платежной системе |
| apple_pay_payment_data | Данные закодированные в base64, полученные в newсобытии onpaymentauthorized в параметре event.payment. |
| Пример: | |
| session.onpaymentauthorized = (event) => { | |
| console.log(event.payment); | |
| } | |
В ответ приходит:
| transactionStatus | Статус операции | Approved - Успешно / Declined - Отказ / On-payment- в процессе/ 3ds - необходима проверка 3 ds |
|---|---|---|
| reason | Текстовая причина отказа | |
| reasonCode | Код ответа | |
| d3AcsUrl | acs url для проверки 3DS | Нет |
| d3Md | Уникальный идентификатор для передачи на хост 3DS | Нет |
| d3Pareq | PaReq сообщение для передачи на хост 3DS | Нет |
| d3Creq | Запрос который необходимо передать на ACS2 сервер (если используется протокол 3DS2) | Нет |
| transaction_key | Ключ транзакции для подтверждения 3DS | Да |
После вызова этого метода приходит callback в backend торговца.
Проверка 3DS
Если в поле status вернется значение 3ds необходимо выполнить проверку 3D Secure.
Если в ответе code пришло значение 2001 необходимо провести проверку 3DS.
Для проверки 3ds необходимо методом POST отправить форму с параметрами d3Md, d3Pareq, termUrl на d3AcsUrl.
term_url - url на который вернется результат проверки 3DS.
<form name="MPIform" action='${d3AcsUrl}' method="POST">
<input type="hidden" name="PaReq" value='${d3Pareq }'>
<input type="hidden" name="MD" value='${d3Md }'>
<input type="hidden" name="TermUrl" value='${termUrl}'>
</form>
Если в ответе code пришло значение 2002 необходимо провести проверку по протоколу 3DS2.
Для проверки 3ds необходимо методом POST отправить форму с параметром d3Creq на d3AcsUrl.
termUrl - url на который вернется результат проверки 3DS.
<form name="MPIform" action='${d3AcsUrl}' method="POST">
<input type="hidden" name="creq" value='${d3Creq }'>
</form>
После прохождения клиентом аутентификации и редиректа на TempUrl с результатом, полученным от эмитента, мерчант направляет запрос Complete3DS.
Параметры запроса:
| Параметр | Описание | Обязтельный |
|---|---|---|
| operation | Тип операции | Complete3DS |
| transaction_key | Ключ транзакции | |
| merchant_id | Идентификатор мерчанта | |
| d3ds_md | Идентификатор полученный после редиректа с сервера ACS (для 3DS2 передавать пустое поле, и в подписи тоже) | |
| d3ds_pares | Сообщение полученное после редиректа с сервера ACS (для 3DS2 передавать пустое поле, и в подписи тоже) | |
| d3ds_cres | Сообщение полученное после редиректа с сервера ACS (Только для 3DS2) | |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,transaction_key,d3ds_md,d3ds_pares разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
Параметры ответа
| Параметр | Описание | Обязтельный |
|---|---|---|
| status | Статус платежа справочник “Статусы платежа” | Да |
| code | Код ответа. Справочник “Коды ответов” справочник “Статусы платежа” | Да |
| order_id | Уникальный номер заказа в системе торговца | Да |
| amount | Сумма платежа | Да |
| fee | Комиссия | Да |
| currency | Валюта платежа | Да |
| card_pan | Маскированный номер карты | Да |
| transaction_id | Идентификатор транзакции | Да |