УКР | [ENG](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg)
:arrow_left: [На Головну](/Mj2ZqCVpSq6A6Jzm6ladlw)

# Оплата картою Server-Server

:::info
[TOC]
:::

## Що таке "оплата картою Server-Server"?
Це прийом оплати картою від клієнта на сайті Партнера без переходу клієнта на платіжну сторінку Оператора. Клієнт вводить реквізити карти безпосередньо на сторінці Партнера.

:::warning
Для проведення оплат методом Server-Server Партнеру необхідно мати підтверджений сертифікат [PCI DSS](https://uk.wikipedia.org/wiki/PCI_DSS) (Payment Card Industry Data Security Standard) відповідного рівня, в залежності від кількості операцій на рік.
:::

## Автентифікація відправника платежу

У процесі виконання платежу проводиться автентифікація відправника за допомогою технології [3DSecure 2.0](https://uk.wikipedia.org/wiki/3-D_Secure). Якщо карта відправника не підтримує технологію 3DSecure, то аутентифікація виконується за допомогою AV-транзакції на нульову суму.

Для цього Партнеру віддається код HTML сторінки в кодуванні base64, яку необхідно вивести на сайті:

- **для карт, що підтримують технологію 3DSecure** - віддається код HTML сторінки з автоматичним перенаправленням на сервер ACS банку емітента (Access Control Server), де відображається поле для введення одноразового паролю (тобто коду підтвердження, який для кожної операції призначає емітент картки).
- **для карт, що не підтримують технологію 3DSecure** - віддається код HTML сторінки з полем для введення одноразового паролю (тобто перевірочного коду, вказаного в полі призначення при списанні на нульову суму).

:::success
<details>
<summary>Приклад "3dsHtml"</summary>
<br>

~~~md
{
"Code": 102,
"Message": "needACS",
"Data": {
"3dsHtml": "PCFET0NUWVBFIGh0bWwgUFVCTElDICItLy9XM0MvL0RURCBIVE1MIDQuMDEgVHJhbnNpdGlvbmFsLy9FTiIKCSJodHRwOi8vd3d3LnczLm9yZy9UUi9odG1sNC9sb29zZS5kdGQiPgo8aHRtbD4KPGJvZHkgb25sb2FkPSJkb2N1bWVudC5nZXRFbGVtZW50QnlJZCgnYWNzJykuc3VibWl0KCkiPgo8Zm9ybSBpZD0iYWNzIiBtZXRob2Q9IlBPU1QiIGFjdGlvbj0iaHR0cHM6Ly8zZHMuc2VydmVyL3Byb2Nlc3MvMGEyZGU5Ij4KPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iUGFSZXEiIHZhbHVlPSJlSnhWVDBFVFlqUDhDMVVoVFpRPT0iPgo8aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJNRCIgdmFsdWU9IjI2ODY2Ij4KPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iVGVybVVybCIgdmFsdWU9Imh0dHBzOi8vcmV0dXJuLnhwYXkudWEvQVl6dnZ4LzMwNzIvMzY2Ij4KPC9mb3JtPgo8L2JvZHk+CjwvaHRtbD4=",
"LongPollerID": "63453891",
"OperationID": 63453891,
"OperationStatus": 2
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

## Як працює оплата картою Server-Server

1. Клієнт оформляє покупку та заповнює реквізити картки на сайті Партнера.
2. Партнер формує запит Оператору (наприклад, [[10102] "Карта-гаманець"](https://hackmd.io/jxzgAy4nSt-Q-6chgRCZdQ)), в якому передає номер картки, термін дії та CVV, а також решту параметрів відповідно до технічної документації.
3. Оператор обробляє запит та повертає результат.

## Структура "BrowserData"

Для проведення платежу за допомогою технології *3DSecure версії 2.0* опціонально передаються параметри браузера відправника платежу (за відсутності - Оператор отримує їх самостійно):

| Параметр | Обов'яз-ковість | Тип | Опис | Приклад |
|:----:|:----:|:----:|----|:----:|
|`device`|Ні|Структура| Структура, що передає дані про тип каналу інтерфейсу, де поле `channel` може мати значення: </br> `APP` – канал мобільного додатку, </br> `BRW` - канал Web-додатку. </br> Для каналу `3RI` підготовка до 3DS не виконується.|`BRW`|
|`browserIP`|Ні / </br> Так - для запитів [10101], [10102]|Рядок|IP-адреса відправника.|`146.120.244.242`|
|`browserTZ`|Ні|Ціле|Різниця у часі в порівнянні з UTC, у хвилинах.|`180`|
|`browserLanguage`|Ні|Рядок|Мова інтерфейсу. Максимальна довжина - 8 символів.|`UA`|
|`browserUserAgent`|Ні|Рядок|Значення заголовка “User-Agent”. Максимальна довжина - 2048 символів. |Див. нижче.|
|`browserColorDepth`|Ні|Ціле|Код розрядності кольору дисплея. Можливі значення: `1`, `4`, `8`, `15`, `16`, `24`, `32`, `48`.|`24`|
|`browserJavaEnabled`|Ні|Рядок|Дозвіл використання у браузері Java. Можливі значення: `true`/`false`. |`false`|
|`browserScreenWidth`|Ні|Ціле|Роздільна здатність екрана - ширина.|`1920`|
|`browserScreenHeight`|Ні|Ціле|Роздільна здатність екрану - висота.|`1080`|
|`fraudhuntFingerprint`|Ні|Рядок|[Цифровий відбиток браузера](https://uk.wikipedia.org/wiki/%D0%A6%D0%B8%D1%84%D1%80%D0%BE%D0%B2%D0%B8%D0%B9_%D0%B2%D1%96%D0%B4%D0%B1%D0%B8%D1%82%D0%BE%D0%BA_%D0%BF%D1%80%D0%B8%D1%81%D1%82%D1%80%D0%BE%D1%8E).|Див. нижче.|
|`challengeWindowSize`|Ні|Ціле|Код розміру вікна при взаємодії із клієнтом у рамках "challenge". Можливі значення: `01`, `02`, `03`, `04`.|`01`|

:::success
<details>
<summary>Приклад структури "BrowserData"</summary>
<br>

~~~md
{
"BrowserData": {
"device": {
"channel": "BRW"
},
"browserIP": "146.120.244.242",
"browserTZ": 180,
"browserLanguage": "ru-RU",
"browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36",
"browserColorDepth": 24,
"browserJavaEnabled": false,
"browserScreenWidth": 1920,
"browserScreenHeight": 1080,
"fraudhuntFingerprint": "kHqPGWS1Mj18sZFsP8Wl"
}
}
~~~
</details>
:::

## Редирект клієнта на сторінку CallbackURL

Після проведення операції відбувається перенаправлення клієнта на сторінку результатів оплати **"CallbackURL"** (якщо параметр переданий у запиті), наприклад:

"CallbackURL": "https://partner.host/resul_page"

## Отримання статусу транзакції на URL адреси "SuccessCallback/FailedCallback"

Завершальним етапом виконання операції є отримання статусу транзакції на відповідні URL адреси Партнера - **“SuccessCallback”** або **“FailedCallback”** (якщо параметри передані у запиті), наприклад:

“SuccessCallback”: “https://partner.host/cb_success”
або
“FailedCallback”: “https://partner.host/cb_fail”

При формуванні даних URL адрес додаються параметри `state` та `xrayOperationID`:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
|`state`|Ні|Ціле|Статус обробки операції, згідно таблиці “[Статус обробки операції](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w#%D0%A1%D1%82%D0%B0%D1%82%D1%83%D1%81-%D0%BE%D0%B1%D1%80%D0%BE%D0%B1%D0%BA%D0%B8-%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D1%96%D1%97-%E2%80%9COperationStatus%E2%80%9D)”. |`10` - успішне списання, </br> `21` - помилка проведення операції.|
|`xrayOperationID`|Ні|Рядок|Унікальний ідентифікатор операції у системі Оператора.|`245786`|

:::success
<details>
<summary>Приклад URL адреси "Успішне списання коштів"</summary>
<br>

~~~md
https://partner.host/cb_success?state=10&xrayOperationID=245786
~~~
</details>
:::

:::success
<details>
<summary>Приклад URL адреси "Помилка проведення операції"</summary>
<br>

~~~md
https://partner.host/cb_fail?state=21&xrayOperationID=245786
~~~
</details>
:::

## Отримання поточного статусу операції

Для отримання поточного статусу транзакції у будь-який момент може застосовуватись запит: [[20003] "Отримання статусу операції"](https://hackmd.io/fvd8btZLQXywluia6w5uxg).

## Тестове списання/зарахування на карту

Для тестування операцій списання/зарахування коштів під час розробки використовується "тестове середовище", при цьому реальне списання та зарахування не відбувається.

Тестове середовище: `https://stage-papi.xpay.com.ua:488/xpay`

Для виконання операції списання/зарахування необхідно вказати валідний номер картки. Після цього буде показано імітацію сторінки 3DS (тестову сторінку) з двома кнопками: для успішного та не успішного завершення операції. При цьому будуть викликані потрібні Callback-и та здійснені перенаправлення на необхідні сторінки.

Номер картки для отримання **успішної відповіді** по операції зарахування:
`8888888888888888`.

Номер картки для отримання **неуспішної відповіді** по операції зарахування:
`4000000000000010`.

## Пов'язані запити

[[10101] Карта-карта](https://hackmd.io/ZpBbYAb4RsaTc8NU_0zwfA)
[[10102] Карта-гаманець](https://hackmd.io/jxzgAy4nSt-Q-6chgRCZdQ)
[[10103] Карта-IBAN фізична особа](https://hackmd.io/mQFXiO1USRuVX2-ah4h1FQ)
[[101031] Карта-IBAN юридична особа](https://hackmd.io/-jgdOWRiRwaabSv5_YjAKQ)
[[10150/10051] Карта-телефон-карта](https://hackmd.io/rXZuYXYwQp2W-QffXO99yA)

**Оплата по токену**

[[104021] Оплата картою по токену](https://hackmd.io/CCEZ0su4T3OBtY-_QBSzew)
[[104121] Автосписання з карти по токену (МОТО-операції)](https://hackmd.io/-_Rj-iqZTMy22FxFgUc08w)

**Отримання даних карти**

[[20400/20410] Отримання даних карти за номером телефону](https://hackmd.io/EjF35e_sSfKad2ojsEoYWQ)
[[20404] Отримання даних карти за токеном](https://hackmd.io/Fo0-oeZ4Sz-Gju6Qg01hiA)

## Довідкові матеріали

Опис загальних параметрів системи XPAY див. у розділі ["Довідкові матеріали"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w): коди типів операцій, типи платіжних методів, коди статусів обробки операцій, відомості та помилки, що повертаються у відповіді та ін.

:arrow_left: [На Головну](/Mj2ZqCVpSq6A6Jzm6ladlw)
:arrow_left: [Загальна інформація по підключенню (API)](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA)

<details>
<summary>Служба підтримки XPAY</summary>
</br>

Телефон: [phone]
Email: [e-mail]
Telegram: @xpaysupportbot
</details>