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

# Інтеграція Checkout за структурованим посиланням

:::info
[TOC]
:::

*Що таке Checkout, типи платежів та методи інтеграції див. у розділі ["Checkout"](https://hackmd.io/0mVv8NSpR1SBlFDoUtK5GQ).*

## Як працює Checkout за структурованим посиланням

1. Клієнт оформлює замовлення на сайті Партнера та натискає кнопку оплати (див. схему нижче).
2. Партнер створює структуроване посилання на сторінку оплати (URI1) у вигляді:
:::info
enviroment.url/uk/frame/widget/banner-payment?<параметри платежу>
:::

3. Відбувається редірект клієнта на дану форму оплати, де відображаються усі необхідні атрибути платежу.
4. Клієнт обирає платіжний метод (або заповнює реквізити картки) та підтверджує оплату.
5. В завершення - клієнту відображається сторінка з результатом оплати, а Партнер отримує відповідь від Оператора про статус операції (CallBackURL). Див. деталі у розділі "[[pay/error/refund] Статус операції (CallBackURL)](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ)".

## Схема роботи Checkout за структурованим посиланням


## Формування короткого посилання

Для отримання короткого посилання на оплату (наприклад, для надсилання в СМС/Viber/Telegram/та ін.) здійснюється запит методом “GET” на адресу:
:::info
enviroment.url/uk/frame/widget/banner-link?<параметри платежу>
:::

Результатом є відповідь Оператора у вигляді JSON структури:

:::info
{"shorturl": "коротке посилання на сторінку оплати"}
:::

## URI

Необхідні URI для роботи в залежності від середовища:

**Тестове середовище**

https://stage-mapi.xpay.com.ua

**Продуктове середовище**

https://mapi.xpaydirect.com

## Білдер структурованого посилання

Для ручного формування структурованого посилання можна скористатись інструментом за адресою:

**Тестове середовище**

https://stage-mapi.xpay.com.ua/en/sl/builder

**Продуктове середовище**

https://mapi.xpaydirect.com/en/sl/builder

:::success
<details>
<summary>Приклад формування структурованого посилання через білдер</summary>
<br>

https://stage-mapi.xpay.com.ua/uk/sl/builder?pid=7380bc60-f656-4e51-8d4f-a354a9b68f21&acc=12345&sum=111&data={"Phone":"380671234567", "ClientIP":"8.8.8.8", "FirstName":"Олексій", "LastName":"Бондар", "RegistryAttr":[{"Caption":"acc_id", "Value":1234}], "PaymentInfo":[{"Caption":"Адреса", "Value":"Бульвар Морський, 54"}, { "Caption":"P/Р", "Value":1234}],"Callback": {"PaySuccess": {"URL": "http://google.com/"}}}
</details>
:::

## Формування параметрів

:::warning
*Особливості:*
* Усі назви параметрів: регістрозалежні.
* Сума передається: у копійках (1 грн. відповідає значенню "100").
* Телефон передається: у міжнародному форматі без знака “+”.
* Роздільник між параметрами: символ "&".

:::
| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `pid` | Так | Рядок | Додатковий токен Партнера (не плутати з Partner Token), що надається Оператором додатково для ідентифікації Партнера при кожному запиті. |`7380bc60-f656-4e51-8d4f-a354a9b68f21` |
| `acc` | Ні | Рядок | Ідентифікатор клієнта у системі Партнера: телефон, email або інше кастомне значення (ID). Параметр передається для відображення у платіжній формі клієнта. | `380638754213` </br> або `12345`|
| `sum` | Ні |Ціле|Сума оплати у копійках. Параметр передається для відображення суми у формі оплати. Параметр не може бути зміненим клієнтом, але при необхідності може бути надана така можливість. | 1 грн.=>`100` |
| `data`^1^ | Ні |Структура | Структура даних, що передає додаткову інформацію для проведення операції та відображення на сторінці оплати. | `JHGHJGJS32KDKLJALKJ` |

:::warning
^1^ *Вміст “data” - JSON структура, стиснута у GZIP формат та закодована у base64.
Набір параметрів структури даних “data” формується аналогічно до структури даних “Data” запиту [[10005] Отримання посилання на платіжну сторінку](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg)*.
:::

## Приклади формування структурованого посилання

:::success
<details>
<summary>Приклад формування структурованого посилання</summary>
<br>

**enviroment.url/uk/frame/widget/banner-payment?pid=7380bc60-f656-4e51-8d4f-a354a9b68f21&acc=12345&sum=5000&data=JHGHJGJS32KDKLJALKJ**

де:
pid=7380bc60-f656-4e51-8d4f-a354a9b68f21,
acc=12345,
sum=5000,
data=JHGHJGJS32KDKLJALKJ - *JSON структура, стиснута у GZIP формат та закодована у base64.*
</details>
:::

:::success
<details>
<summary>Приклад формування псевдокоду</summary>
<br>

~~~md
data = urlencode( base64( gzip( json_encode( {"atrr1": "abc", "atrr2": 123} ) ) ) )
~~~
*[Псевдокод - це >>](https://uk.wikipedia.org/wiki/%D0%9F%D1%81%D0%B5%D0%B2%D0%B4%D0%BE%D0%BA%D0%BE%D0%B4)*
</details>
:::

:::success
<details>
<summary>Приклад формування структурованого посилання на PHP</summary>
<br>

~~~md
$json = '{"Phone":"380671234567", "ClientIP":"8.8.8.8", "FirstName":"Олексій", "LastName":"Бондар", "RegistryAttr":[{"Caption":"acc_id", "Value":1234}], "PaymentInfo":[{"Caption":"Адреса", "Value":"Бульвар Морський, 54"}, { "Caption":"P/Р", "Value":1234}]}';
$gzdata = gzencode($json);
$data = urlencode(base64_encode($gzdata));
$url = 'enviroment.url/uk/frame/widget/banner-payment?pid=7380bc60-f656-4e51-8d4f-a354a9b68f21&acc=1234&data=' . $data;
~~~
</details>
:::

## Протокол двостадійної взаємодії

Коли платіжна сторінка Партнера передбачає авторизацію клієнта (введення телефону/email), та у ході обробки даних на стороні Оператора виникає необхідність перевірки реквізитів оплати та/або уточнення суми оплати - застосовується протокол двостадійної взаємодії.

Див. деталі у розділі "[Протокол двостадійної взаємодії. Запит "check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)".

## Запити "pay/error/refund" (CallBackURL)

Завершальним етапом у виконанні операції є надсилання нотифікацій Партнеру про статус операції у вигляді одного з запитів:
* **"pay"** (оплата завершена),
* **"error"** (помилка оплати),
* **"refund"** (здійснено повернення).

Див. деталі у розділі "[Запити "pay/error/refund" (CallBackURL)](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ)".

## Тестові дані

:::info
Для тестування будь-яких операцій та ознайомлення з сервісами системи XPAY заведено **Тестового Партнера**, для якого надано всі необхідні дозволи. Параметри необхідні для тестування Checkout за структурованим посиланням: **URI**, **"pid"** та **"public key XPAY"**.

**URI** тестового середовища:
~~~
https://stage-mapi.xpay.com.ua/uk/frame/widget/banner-payment?<параметри платежу>
~~~

Унікальний ідентифікатор Тестового Партнера **"pid"**:
~~~
pid=7380bc60-f656-4e51-8d4f-a354a9b68f21
~~~

Публічний ключ Оператора **"public key XPAY"** для тестового середовища:

~~~
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0IH2V0Ot1ej4FdOihujG
ON37sqql62vFFR/4IK+w4xqHRvD+SEwwkLL9EO72e42bV9VaKOqKbX81A+0hbBXi
W7axjHU2Sc97EXTHjpwX++HduUXbXhRteyzcHDLZCGKT8WzoNgQeXcieLUYUp2bb
gjElGecKprcprkMeHmffmelwlzcv61auGU0o10CTyyCqhOKofdqJq6A2KOBCLL49
5z1700oCRo9qL4loe95r4wGh6AmHZNvAnAwLgzwzyLvWCz479CVIWEaMY/+uczfL
0yRjN+8uqNK3A09wOD+wO1I+YfU9YXcQ75L8ibxzWcNgMHrhJQ9ZtnoVltiTWEEB
9QIDAQAB
-----END PUBLIC KEY-----
~~~
:::

:arrow_left: [На Головну](/Mj2ZqCVpSq6A6Jzm6ladlw)
:arrow_left: [Checkout](https://hackmd.io/0mVv8NSpR1SBlFDoUtK5GQ)

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

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