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

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

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

## Застосування

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

У цьому випадку операція проведення платежу виконується у дві стадії:

1. Оператор надсилає Партнеру запит "**check**" для уточнення даних та перевірки можливості проведення операції по клієнту.
2. По завершенню операції Оператор надсилає нотифікацію Партнеру про статус операції у вигляді одного з запитів: **"pay/error/refund"**, що описані у розділі "[[pay/error/refund] Статус операції (CallBackURL)](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ)".

## Схема роботи протоколу двостадійної взаємодії


## Особливості формування запиту

* Протокол двостадійної взаємодії може застосовуватись лише при здійсненні оплати через платіжну сторінку (Checkout) при будь-якому методі інтеграції (див. розділ "[Методи інтеграції Checkout](https://hackmd.io/0mVv8NSpR1SBlFDoUtK5GQ?both#%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D0%B8-%D1%96%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D1%96%D1%97-Checkout)").
* Запит виконується на URL адресу (параметр `CallBackURL` структури `Data`), передану у запиті [[10005]](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg).
* Запит надсилається одноразово, та у випадку відсутності відповіді - надходить сповіщення про помилку проведення операції.
* Запит здійснюється методом "GET" та передається у вигляді рядка.
* Сума передається: у копійках (1 грн. відповідає значенню "100").
* Телефон передається: у міжнародному форматі без знака “+”.
* Роздільник між параметрами: символ "&".

## Запит "check"

У запиті передаються наступні параметри:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `command` | Так | Рядок | Тип запиту. | `check` |
| `txn_id` | Так | Рядок | Унікальний ідентифікатор транзакції у системі Оператора. | `321455` |
| `uuid` | Так | Рядок | Унікальний ідентифікатор, що зв'язує запити "check" та "pay/error/refund". | `f3cd72b6-e1ea-406f-9b44-a9b93b401b7f` |
| `account` | Так | Рядок | Унікальний ідентифікатор клієнта у системі Партнера: телефон або email. | `380638754213` |
| `sum` |Так |Ціле|Сума операції у копійках.|1 грн.=>`100`|
| `pay_type` | Так | Рядок | Тип платіжного методу. Див. таблицю ["Типи платіжного методу "PayType"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w#%D0%A2%D0%B8%D0%BF%D0%B8-%D0%BF%D0%BB%D0%B0%D1%82%D1%96%D0%B6%D0%BD%D0%BE%D0%B3%D0%BE-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%83-%E2%80%9CPayType%E2%80%9D). | `1` |
| `locale` | Так | Рядок | Локаль (мова) платіжної сторінки (відповідає переданій локалі за запитом [[10005]](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg)). | `uk` |

:::success
<details>
<summary>Приклад запиту "check"</summary>
<br>

https://partner.host/protocol?command=check&txn_id=321455&uuid=f3cd72b6-e1ea-406f-9b44-a9b93b401b7f&account=380638754213&sum=100&pay_type=1&locale=uk

</details>
:::

## Відповідь на запит "check"

На запит "check" Партнер надсилає відповідь у вигляді JSON структури, що формується з наступних параметрів:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `txn_id` | Так | Рядок | Унікальний ідентифікатор транзакції, переданий у запиті "check". | `321455` |
| `result` | Так | Рядок | Статус обробки операції, згідно таблиці “[Статус обробки операції](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` |
| `message` | Ні | Рядок | Текстове повідомлення з описом результату. | `Ок` |
| `info` | Так | Структура | Структура даних, що передає інформацію про деталі платежу (суму та ін.) для проведення операції та відображення на платіжній сторінці. Параметри структури описані нижче. | Див. приклад нижче. |

### Параметри структури "info"

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `client_name` | Ні | Рядок | ПІБ клієнта. | `Кіндратенко Генадій Йосипович` |
| `contract_number` | Ні | Рядок | Номер замовлення у системі Партнера. | `98-00ФАВ` |
| `max_sum`^1^ | Так/Ні | Рядок | Максимально допустима сума платежу у копійках. Може бути змінена клієнтом, на меншу, але не більшу. | 1 грн.=>`100` |
| `fixed_sum`^1^ | Так/Ні | Рядок | Фіксована сума платежу у копійках. Не може бути змінена клієнтом. | 1 грн.=>`100` |
| `float_sum`^1^ | Так/Ні | Рядок | Сума платежу у копійках, введена клієнтом вручну. | 1 грн.=>`100` |
| `currency` | Так - при оплаті у валюті, відмінній від UAH | Рядок | Код валюти списання – скорочене буквене позначення валюти, описане в стандарті [ISO 4217](https://uk.wikipedia.org/wiki/%D0%9A%D0%BB%D0%B0%D1%81%D0%B8%D1%84%D1%96%D0%BA%D0%B0%D1%86%D1%96%D1%8F_%D0%B2%D0%B0%D0%BB%D1%8E%D1%82_(ISO_4217)) (“GBP”, “USD” та ін.). | `AUD` |
| `account`^2^ | Ні | Структура | Дані для оплати за реквізитами. Параметри структури описані нижче. | Див. приклад нижче.|

:::warning
^1^ Один з параметрів `max_sum`, `fixed_sum` або `float_sum` - є обов'язковим для заповнення та передається для **відображення суми оплати** на платіжній сторінці. При заповненому полі `PaymentSum` запиту [[10005]](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg) - Оператор не здійснює запит "check" для визначення суми оплати.

^2^ Параметр `account` застосовується лише при проведенні "[оплати за реквізитами](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w?both#%D0%A2%D0%B8%D0%BF%D0%B8-%D0%BF%D0%BB%D0%B0%D1%82%D1%96%D0%B6%D0%BD%D0%BE%D0%B3%D0%BE-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%83-%E2%80%9CPayType%E2%80%9D)" (`"PayType":"4"` або `"PayType":"5"`) - коли необхідно отримати дані реквізитів для оплати.
:::

### Параметри структури “account”

| Параметр| Обов’яз-ковість |Тип | Опис|Приклад|
|:----:|:----:|:---:|----|:-----:|
| `EDRPOU` | Так | Рядок | ЄДРПОУ отримувача. | `34190717` |
| `Account` | Так | Рядок | IBAN отримувача (міжнародний номер банківського рахунку). | `UA4030034600000-26008010065101` |
| `MFO` | Так | Рядок | МФО банку отримувача. | `305299` |
| `Purpose` | Так | Рядок | Призначення платежу. | `Оплата замовлення №543345` |
| `SenderName` | Так | Рядок | ПІБ відправника платежу. | `Дзюба А.І.` |
| `RecipientName` | Так | Рядок | ПІБ отримувача платежу. | `Шевченко Т.Г.` |

:::success
<details>
<summary>Приклад структури відповіді</summary>
<br>

~~~md
{
"txn_id": "321455",
"result": "10",
"message": "Ok",
"info": {
"client_name": "Кіндратенко Генадій Йосипович",
"contract_number": "98-00ФАВ",
"fixed_sum": "3189"
}
}
~~~
</details>
:::

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

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

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

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

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