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

# [pay/error/refund] Статус операції (CallBackURL)

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

## Надсилання нотифікацій Партнеру

Завершальним етапом у виконанні операції є надсилання нотифікацій Партнеру про **статус операції** у вигляді одного з запитів:

* **"pay"** (оплата завершена),
* **"error"** (помилка оплати),
* **"refund"** (здійснено повернення).

Загальний алгоритм проведення операції див. у розділі "[Схема роботи API Checkout](https://hackmd.io/DyX9oooaR6OLe5MkdwqllA#%D0%A1%D1%85%D0%B5%D0%BC%D0%B0-%D1%80%D0%BE%D0%B1%D0%BE%D1%82%D0%B8-API-Checkout)".

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

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

## Запит "pay/error"

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

| Параметр | Обов’яз-ковість | Тип | Опис |Приклад |
|:-:|:-:|:-:|-|:-:|
| `command` | Так | Рядок | Статус проведеної операції: </br> - "pay" - оплата завершена, </br> - "error" - помилка оплати. | `pay` або `error` |
| `txn_id` | Так | Рядок | Унікальний ідентифікатор транзакції у системі Оператора. При отриманні запиту "pay" з параметром `txn_id`, який раніше вже передавався - запит слід вважати повторним, при цьому не повинна генеруватись нова транзакція. | `321455` |
| `uuid` | Так | Рядок | Унікальний ідентифікатор, що зв'язує запити "check" та "pay/error/refund". | `f3cd72b6-e1ea-06f-9b44-a9b93b401b7f` |
| `account` | Так | Рядок | Унікальний ідентифікатор клієнта у системі Партнера: телефон або email. | `380638754213` |
| `sum` |Так |Ціле|Сума операції у копійках.|1 грн.=>`100` |
| `pay_type` | Так | Рядок | Тип платіжного методу. Див. [перелік типів](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` |
| `txn_date` |Так|Рядок| Дата та час проведення операції. Формат: YYYYMMDDHHMMSS.| `20190301180233` |
| `card_token` |Ні|Рядок| Токен картки. Параметр передається, якщо у Партнера ввімкнена опція токенізації карт (використовується лише для запиту "pay").| `c0bbb6318f7c442- 2b9d787bc9724145-2c0d9250cdd2a1d` |
|`txn_id_own`|Ні|Рядок| Унікальний ідентифікатор транзакції у системі Партнера: `TransactionID`, надісланий в запиті [[10005]](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg). |`5c6e2be`|
| `locale` | Так | Рядок | Локаль (мова) платіжної сторінки (відповідає переданій локалі за запитом [[10005](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg)]). | `uk` |
| `sign` |Ні|Рядок| Підпис сформований за допомогою приватного ключа з [конкатенації](https://uk.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BD%D0%BA%D0%B0%D1%82%D0%B5%D0%BD%D0%B0%D1%86%D1%96%D1%8F) рядків даних: </br> `txn_id`+`uuid`+`txn_date`+`sum`. </br> Алгоритм формування підпису див. у розділі ["Загальна інформація по підключенню (API)"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA). |`uDzPcuDjEFlC2FG-2Mjr566GKGIArfK-kcIA3LYTcXmavB3-9QBGmlVyU2yXG64-TM4qDq2kMBxXOQR-ueBMDcYgYkycyTd-Y8Q%3D%3D`|

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

~~~md
txn_id=321456
uuid=f3cd72b6-e1ea-406f-9b44-a9b93b401b7f
txn_date=20190301180233
sum=100
~~~
Рядок для підпису:
~~~md
321456f3cd72b6-e1ea-406f-9b44-a9b93b401b7f20190301_180233100
~~~
</details>
:::

:::success
<details>
<summary>Приклад запиту “pay”</summary>
<br>

~~~md
https://partner.host/protocol?command=pay&txn_id=321456&uuid=f3cd72b6-e1ea-406f-9b44-a9b93b401b7f&account=380638754213&sum=100&pay_type=1&txn_date=20190301180233&locale=uk&sign=uDzPcuDjEFlC2FG2Mjr566GKGIArfKkcIA3LYTcXmavB39QBGmlVyU2yXG64TM4qDq2kMBxXOQRueBMDcYgYkycyTdY8Q%3D%3D
~~~
</details>
:::

## Запит "refund"

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

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `command` | Так|Рядок|Статус проведеної операції: "refund" - здійснено повернення.|`refund`|
| `txn_id` | Так | Рядок | Унікальний ідентифікатор транзакції у системі Оператора. | `321455` |
| `sum` | Так |Ціле|Сума операції у копійках. |1 грн.=>`100` |
| `operation_id` | Так | Рядок | Унікальний ідентифікатор операції у системі Оператора. | `11` |
| `partner_txn_id` | Так | Рядок | Унікальний ідентифікатор транзакції у системі Партнера. | `321455` |
| `partner_terminal_id` | Так | Рядок | Унікальний ідентифікатор терміналу у системі Партнера. | `1` |
| `txn_date` |Так|Рядок| Дата та час проведення операції у форматі: YYYYMMDDHHMMSS.| `20190301180233` |
| `sign` |Ні|Рядок| Підпис сформований за допомогою приватного ключа з конкатенації рядків даних: </br> `sum`+`txn_id`+`partner_txn_id`+ `partner_terminal_id`. </br> Алгоритм формування підпису описаний у розділі ["Загальна інформація по підключенню (API)"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA). |`uDzPcuDjEFlC2FG-2Mjr566GKGIArfK-kcIA3LYTcXmavB3-9QBGmlVyU2yXG64-TM4qDq2kMBxXOQR-ueBMDcYgYkycyTd-Y8Q%3D%3D` |

## Відповідь на запит "pay/error/refund"

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

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `txn_id` | Так | Рядок | Унікальний ідентифікатор транзакції, переданий у запиті "pay/error/refund". | `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` | Ні | Рядок | Текстове повідомлення з описом результату. | `Ок` |
| `txn_date` |Так|Рядок| Дата та час проведення операції у системі Партнера. Формат: YYYYMMDDHHMMSS.| `20190301180233` |

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

~~~md
{
"txn_id": "321456",
"result": "10",
"message": "Done",
"txn_date": "20190301180833"
}
~~~
</details>
:::

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

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

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

Опис загальних параметрів системи 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>