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

# [10005] Отримання посилання на платіжну сторінку

:::info
[TOC]
:::

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

:::warning
За замовчуванням платіжна сторінка доступна протягом 15 хвилин. За необхідності, даний відрізок часу може змінюватись у параметрі `TTL` в структурі "Data" (див. нижче) або встановлюватись в налаштуваннях системи Оператора.
:::

## Запит

*Опис атрибутів "Partner", "KeyAES" та "Sign" див. у розділі ["Загальна інформація по підключенню (API)"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA).*

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

Структура "Data" для даної операції формується з наступних параметрів:

:::info
<details>
<summary>Формування структури "Data" (приклади наведені нижче)</summary>
<br>

~~~
{
"PayType": "",
"Phone": "",
"Email": "",
"Account": "",
"FirstName": "",
"LastName": "",
"MiddleName": "",
"IPN": "",
"PaymentSum": ,
"Order": "",
"Purpose": "",
"ClientIP": "",
"PanSuffix": "",
"Currency": "",
"Exchnge": "",
"Signature": "",
"AccountID": "",
"Sum": "",
"BrowserFingerprint": "",
"RecipientCard": {
"PAN": "",
"FirstName": "",
"MiddleName": "",
"LastName": "",
"IPN": "",
"document_type_id": "",
"doc_series": "",
"doc_number": "",
"dt_doc_issue": "",
"dt_doc_exp": "",
"doc_issued_by": ""
},
"MIDs": [
{
"MID": ,
"Sum": ,
"PaymentInfo": [
{
"Caption": "",
"Value": ""
}
],
"Account": "",
"EDRPOU": "",
"MFO": "",
"Name": "",
"Order": ""
}
],
"PaymentInfo": [
{
"Caption": "",
"Value": ""
}
],
"RegistryAttr": [
{
"Caption": "",
"Value": ""
}
],
"Service": [
{
"ServiceCode": "",
"Sum":
}
],
"Callback": {
"PaySuccess": {
"URL": ""
},
"PayFail": {
"URL": ""
}
},
"BillAttr": {
"PayerAddress": ""
},
"TTL": "",
"CallBackURL": "",
"AccountPayments": [
{
"Sum": ,
"Purpose": "",
"Account": "",
"EDRPOU": "",
"ID": "",
"RecipientName": "",
"SenderName": "",
"IPN": ""
}
],
"ticket": [],
"cashiersignature": "",
"Transaction": {
"TransactionID": "",
"TerminalID": "",
"DateTime": ""
}
}
~~~
</details>
:::

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `PayType` | Ні | Рядок | Тип платіжного методу: </br> `0` або `відсутність параметра` - пряме списання коштів з картки клієнта через с2а (card-to-account) або p2p (person-to-person) переказ; </br> `1` - оплата через шлюз інтернет-еквайрингу; </br> `2` - відкладений платіж^1^; </br> `3` - оплата через сторонній віджет; </br> `4` - оплата за реквізитами^2^; </br> `5` - відкладений платіж за реквізитами^1,2^; </br> `7` - пакетна оплата послуг; </br> `12` - пакетна оплата послуг за реквізитами; </br> `13` - оплата на користь мерчантів (MIDs); </br> `20` - оплата через "Google/Apple Pay". </br> Див. деталі у розділі ["Типи платіжного методу "PayType"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w?view#%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-PayType). | `5` |

:::warning
^1^ При проведенні запитів "відкладеного платежу" (`"PayType":"2"` або `"PayType":"5"`) - Партнер додатково надсилає запит на "[Підтвердження/скасування передавторизації](https://hackmd.io/aTXOGiPaSkewvXdXUbpstg)". У разі відсутності підтвердження - списання коштів буде автоматично скасовано (через відрізок часу, вказаний у договорі з Партнером).

^2^ При проведенні запитів "оплати за реквізитами" (`"PayType":"4"` або `"PayType":"5"`) - Оператор у відповідь надсилає запит "check", на який необхідно повернути дані реквізитів для оплати (див. розділ ["[check] Протокол двостадійної взаємодії"](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)).
:::

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `Phone`^3^ | Ні | Рядок | Телефон клієнта у форматі: "380ххххххххх". |`380679335544`|
| `Email`^3^ | Ні | Рядок | Email клієнта. |`[e-mail]`|
| `Account`^3^ | Ні | Рядок |Ідентифікатор клієнта у системі Партнера: телефон або email. Дані клієнта, у ході обробки яких Оператор може надсилати зустрічний запит "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)" Партнеру. |`380638754213`|

:::warning
^3^ Якщо в запиті не вказано жодного з цих параметрів (`Phone`, `Email` чи `Account`) - Оператор передає посилання на форму для їх введення клієнтом. Після отримання даних виконується запит "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA?view)" для уточнення деталей оплати. Серед полів `Phone` та `Email` більш пріоритетним є `Phone`. Якщо запит необхідно проводити за допомогою email-у, то його слід вказати у полі `Account`.
:::

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `FirstName` | Ні | Рядок | Ім'я клієнта. |`Олег`|
| `MiddleName` | Ні | Рядок | По батькові клієнта. |`Михайлович`|
| `LastName` | Ні | Рядок | Прізвище клієнта. |`Подільський`|
| `IPN` | Умовно-обов’язковий (визначається на етапі інтеграції) | Рядок | Індивідуальний податковий номер (ІПН) платника. |`111111111111`|
|`RecipientCard`^4^|Ні|Структура|Структура, що передає дані банківської картки одержувача.|Див. нижче.|
| `PaymentSum` | Ні | Ціле | Сума оплати у копійках. Параметр передається для відображення суми оплати на платіжній сторінці. При заповненому полі - Оператор не здійснює запит "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)" для визначення суми оплати. |50грн.=>`5000`|
| `Order` | Ні | Рядок |Номер замовлення. |`1234А`|
| `Purpose` |Ні| Рядок | Призначення платежу. |`Оплата замовлення №543345`|
| `ClientIP` | Ні | Рядок | IP адреса, з якої клієнт ініціює операцію. |`127.0.0.1`|
| `PanSuffix` | Ні | Рядок | Останні 4 цифри номера картки, у разі, якщо відбулась попередня верифікація картки. |`3456`|
| `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”, ..). |`USD`|
| `Exchange` | Так - при оплаті у валюті, відмінній від 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”, ..). |`GBP`|
| `BrowserFingerprint` | Ні | Рядок | [Цифровий відбиток браузера](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): [https://m.habr.com/ru/company/oleg-bunin/blog/321294/](https://m.habr.com/ru/company/oleg-bunin/blog/321294/); [https://github.com/valve](https://github.com/valve) |`86a190af26de3a920c62ea19ba0df3a8`|
| `BillAttr` | Ні | Структура | Структура, що передає дані про зворотну адресу клієнта: `PayerAddress`. |`м. Харків, вул. Хіміків 4/59`|
| `Callback` | Ні | Структура | Складається з 2-ох структур даних `PaySuccess` (для обробки успішного платежу) та `PayFail` (для обробки помилки), де поле `URL` - адреса, на яку буде перенаправлений клієнт після завершення оплати. |`"Callback": { "PaySuccess": { "URL": "https://partner.com/callback/success"}, "PayFail": {"URL": "https://partner.com/callback/fail"}}`|
| `CallBackURL` | Ні | Рядок | Адреса Партнера, на яку виконуються запити "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)" та "[pay / error / refund](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ)" для сповіщення про результати оплати. |`https://partner.com/callback/xpay2`|
| `TTL` | Ні | Ціле | Час, протягом якого доступна сторінка для оплати. Параметр вказується в секундах. |`300`|
|`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.|

^4^ Параметри структури **"RecipientCard"**:

| Параметр | Обов'яз-ковість | Тип | Опис | Приклад|
|:----:|:----:|:----:|----|:----:|
|`PAN`|Так|Рядок[16]| PAN картки одержувача (номер банківської карти).| `8888888888888888`|
| `FirstName` | Так* | Рядок | Ім'я одержувача. |`Максим`|
| `MiddleName` | Так* | Рядок | По батькові одержувача. |`Олегович`|
| `LastName` | Так* | Рядок | Прізвище одержувача. |`Кравець`|
| `IPN` | Так* | Рядок | Індивідуальний податковий номер (ІПН) одержувача. |`111111111111`|
| `document_type_id` | Так* | Ціле | Тип документа з довідника: </br> `1` - паспорт, </br> `2` - ID-картка. |`1`|
| `doc_series` | Так* | Рядок | Серія документа. |`19910824-00026`|
| `doc_number` | Так* | Рядок | Номер документа. |`123456789`|
| `dt_doc_issue` | Так* | Рядок | Дата видачі документа. |`2022-06-14`|
| `dt_doc_exp` | Так* | Рядок | Термін закінчення дії документа. |`2022-06-14`|
| `doc_issued_by` | Так* | Рядок | Орган, що видав документ. |`3459`|

**Параметри є умовно-обов’язковими (визначаються на етапі інтеграції).*

</br>

Розглянемо параметри атрибуту "Data", що мають **структуру масивів**.

#### Масив "MIDs"

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `MIDs` | Так для: `PayType`=`"13"` | Масив | Масив, що передає дані для розщеплення прийнятого платежу на користь мерчантів. |Див. приклад нижче.|

Параметри масиву **"MIDs"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `MID` |Так| Ціле | Ідентифікатор мерчанта в системі Оператора (Merchant ID), на який зараховуються кошти. |`111`|
| `Sum` |Так| Ціле | Сума платежу у копійках.|1грн.=>`100` |
| `PaymentInfo` | Ні | Масив | Параметр передається для відображення деталей платежу на сторінці оплати. |Див. приклад нижче.|
| `Account` |Ні| Рядок | Розрахунковий рахунок або IBAN одержувача (міжнародний номер банківського рахунку). | `UA4830529900000 26008031203677`|
|`EDRPOU`|Ні|Рядок | [ЄДРПОУ](https://uk.wikipedia.org/wiki/%D0%84%D0%B4%D0%B8%D0%BD%D0%B8%D0%B9_%D0%B4%D0%B5%D1%80%D0%B6%D0%B0%D0%B2%D0%BD%D0%B8%D0%B9_%D1%80%D0%B5%D1%94%D1%81%D1%82%D1%80_%D0%BF%D1%96%D0%B4%D0%BF%D1%80%D0%B8%D1%94%D0%BC%D1%81%D1%82%D0%B2_%D1%82%D0%B0_%D0%BE%D1%80%D0%B3%D0%B0%D0%BD%D1%96%D0%B7%D0%B0%D1%86%D1%96%D0%B9_%D0%A3%D0%BA%D1%80%D0%B0%D1%97%D0%BD%D0%B8) одержувача.|`3505506226` |
| `MFO` |Ні |Рядок | [МФО](https://uk.wikipedia.org/wiki/%D0%9C%D0%A4%D0%9E) - код банку одержувача. |`305299`|
| `Name` | Ні | Рядок | Назва одержувача. |`ТОВ "Ресурс"`|
| `Order` | Ні | Рядок | Номер замовлення одержувача/номер особового рахунку/тощо. |`123`|

:::success
<details>
<summary>Приклад масиву даних "MIDs"</summary>

~~~md
{
"MIDs": [
{
"MID": 111,
"PaymentInfo": [
{
"Caption": "Призначення",
"Value": "Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна"
}
],
"Sum": 100,
"Account": "UA483052990000000008031203000",
"EDRPOU": "3505501111",
"MFO": "123456"
},
{
"MID": 112,
"PaymentInfo": [
{
"Caption": "Призначення",
"Value": "Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна"
}
],
"Sum": 200,
"Account": "UA483052990000000008031203000",
"EDRPOU": "3505501111",
"MFO": "123456"
}
]
}
~~~
</details>
:::

#### Масив "PaymentInfo"

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `PaymentInfo` | Ні | Масив | Параметр передається для відображення деталей платежу на сторінці оплати. |Див. приклад нижче.|

Параметри масиву **"PaymentInfo"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `Caption` |Так| Рядок | Опис додаткової інформації. |`Призначення`|
| `Value` |Так| Рядок | Додаткова інформація. |`Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна`|

:::success
<details>
<summary>Приклад масиву даних "PaymentInfo"</summary>
<br>
Необхідно відобразити на платіжній сторінці:
<br>
"Призначення: Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна"

~~~md
{
"PaymentInfo": [
{
"Caption": "Призначення",
"Value": "Погашення за контрактом №3642989012-5 від 03.04.2021 Пупкіна Валерія Сергіївна"
}
]
}
~~~
</details>
:::

#### Масив "RegistryAttr"

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `RegistryAttr` | Ні | Масив | Параметр застосовується для формування та відправки звітів Партнера. |Див. приклад нижче.|

Параметри масиву **"RegistryAttr"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `Caption` |Так| Рядок | Назва поля, що відображається у файлі звітності. |`acc_id`|
| `Value` |Так| Рядок | Значення поля, що відображається у файлі звітності.|`123`|

:::success
<details>
<summary>Приклад масиву даних "RegistryAttr"</summary>

~~~md
{
"RegistryAttr": [
{
"Caption": "acc_id",
"Value": "123"
},
{
"Caption": "mdf_id",
"Value": "11011"
}
]
}
~~~
</details>
:::

#### Масив "Service"

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `Service`^5^ | Ні | Масив `ServiceItem` | Масив даних, що передається для оплати пакета послуг. Кожен платіж описується назвою послуги та сумою оплати за послугу. |Див. приклад нижче.|

:::warning
^5^ Параметр передається лише при проведенні запиту [пакетної оплати послуг](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":"7"`), тобто розщеплення платежу клієнта на декількох одержувачів та зарахування коштів на заздалегідь прописані гаманці.
:::

Параметри масиву **"ServiceItem"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `ServiceCode` | Так |Рядок | Буквено-цифрова назва послуги або її постачальника. Перелік даних значень є індивідуальним та визначається в залежності від послуг, що надаються Партнером.|`TEPLO`|
| `Sum` | Так | Ціле | Сума платежу за послугою у копійках. |1грн.=>`100`|

:::success
<details>
<summary>Приклад масиву даних "ServiceItem"</summary>
<br>

~~~md
{
"Service": [
{
"ServiceCode": "TEPLO",
"Sum": 5500
},
{
"ServiceCode": "GAZ",
"Sum": 12000
}
]
}
~~~
</details>
:::

#### Масив "AccountPayments"

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `AccountPayments`^6^ | Ні | Масив `AccountPayment` | Масив даних, що передається для оплати пакета послуг за реквізитами. Кожен платіж описується набором параметрів, наведених нижче.|Див. приклад нижче.|

:::warning
^6^ Параметр передається лише при проведенні запиту [пакетної оплати послуг за реквізитами](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":"12"`), тобто розщеплення платежу клієнта на декількох одержувачів та зарахування коштів на вказані реквізити.
:::

Параметри масиву **"AccountPayments"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `Sum` |Так| Ціле | Сума платежу за послугою у копійках. | 1 грн.=>`100` |
| `Purpose` |Так| Рядок | Призначення платежу. |`Оплата замовлення №543345`|
| `Account` |Так| Рядок | IBAN отримувача (міжнародний номер банківського рахунку). | `UA173052990000026207893720887`|
| `EDRPOU` |Так| Рядок | ЄДРПОУ отримувача. | `34190717` |
| `ID` |Так| Рядок | Унікальний ідентифікатор платежу. |`af1377`|
| `RecipientName` |Так| Рядок | ПІБ отримувача платежу. |`Шевченко Т.Г.`|
| `SenderName` |Так| Рядок | ПІБ відправника платежу.|`Дзюба А.І.`|
| `IPN` |Так| Рядок | Індивідуальний податковий номер платника податків. |`7845325697`|

:::success
<details>
<summary>Приклад масиву даних "AccountPayment"</summary>
<br>

~~~md
{
"AccountPayments": [
{
"Sum": 10000,
"Purpose": "Оплата замовлення №543345",
"Account": "UA173052990000026207893720887",
"EDRPOU": "34190717",
"ID": "af1377",
"RecipientName": "Шевченко Т.Г.",
"SenderName": "Дзюба А.І.",
"IPN": "7845325697"
},
{
"Sum": 20000,
"Purpose": "Оплата замовлення №543000",
"Account": "UA173052990000026207893765656",
"EDRPOU": "33230717",
"ID": "af12277",
"RecipientName": "Муляр О.В.",
"SenderName": "Дзюба А.І.",
"IPN": "7845325697"
}
]
}
~~~
</details>
:::

#### Масив "ticket"

Параметр `ticket` застосовується для формування **фіскального чека** на програмному касовому апараті.

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `ticket`^7^ | Ні | Масив `ticket` | Масив даних, що передає інформацію про товар: ідентифікатор товару, найменування, вартість та кількість. | Див. приклад нижче. |
| `cashiersignature` | Ні | Рядок | Підпис касира. Параметр передається лише при необхідності фіскалізації операції та формування [РРО](https://tax.gov.ua/baneryi/programni-rro/aktualni-zapitannya-vidpovidi/) квитанцій ([реєстратор розрахункових операцій](https://uk.wikipedia.org/wiki/%D0%A0%D0%B5%D1%94%D1%81%D1%82%D1%80%D0%B0%D1%82%D0%BE%D1%80_%D1%80%D0%BE%D0%B7%D1%80%D0%B0%D1%85%D1%83%D0%BD%D0%BA%D0%BE%D0%B2%D0%B8%D1%85_%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D1%96%D0%B9)). | `nvfjdjjfdjdkjf84iewjd` |

:::warning
^7^ **Для фіскалізації чека необхідно:**
1. Партнер реєструється на ресурсі: checkbox.ua (з реєстрацією РРО та касира).
2. У кабінеті "checkbox" самостійно веде: відкриття/закриття зміни та звітність (X, Z).
3. У запиті через параметр `ticket` - Партнер передає інформацію Оператору для реєстрації фіскального чека.
4. На підставі даних запиту Оператор проводить перевірку відповідності суми операції із сумою товарів у чеку.
5. Оператор фіскалізує чек через ресурс: checkbox.ua.
6. В завершення - Оператор надсилає платнику (за погодженням) на email/sms посилання на чек РРО.

**Для реєстрації чека необхідно:**

1. Передати Оператору логін/пароль касира,
АБО
2. Формувати у кожному запиті підпис касира (`cashiersignature`).
:::

Параметри масиву **"ticket"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `ID` |Так|Рядок|Ідентифікатор товару.|`11`|
| `Good` |Так|Рядок|Найменування товару.|`bolt`|
| `Price` |Так| Ціле| Вартість товару в копійках. |1грн.=>`100`|
| `Count` |Так| Ціле | Кількість товару. |1шт.=>`1000` </br> 2.25кг=>`2250`|
| `uktzed` |Ні|Рядок|Цифровий код товару згідно з [УКТ ЗЕД](https://uk.wikipedia.org/wiki/%D0%A3%D0%BA%D1%80%D0%B0%D1%97%D0%BD%D1%81%D1%8C%D0%BA%D0%B0_%D0%BA%D0%BB%D0%B0%D1%81%D0%B8%D1%84%D1%96%D0%BA%D0%B0%D1%86%D1%96%D1%8F_%D1%82%D0%BE%D0%B2%D0%B0%D1%80%D1%96%D0%B2_%D0%B7%D0%BE%D0%B2%D0%BD%D1%96%D1%88%D0%BD%D1%8C%D0%BE%D0%B5%D0%BA%D0%BE%D0%BD%D0%BE%D0%BC%D1%96%D1%87%D0%BD%D0%BE%D1%97_%D0%B4%D1%96%D1%8F%D0%BB%D1%8C%D0%BD%D0%BE%D1%81%D1%82%D1%96) (українська класифікація товарів зовнішньоекономічної діяльності).|`0403`|

:::success
<details>
<summary>Приклад масиву даних "ticket"</summary>
<br>

~~~md
{
"ticket": [
{
"ID": "11",
"Good": "bolt",
"Price": 100,
"Count": 1000
},
{
"ID": "22",
"Good": "vtulka",
"Price": 2500,
"Count": 60000
}
]
}
~~~
</details>
:::

#### Параметри для криптопроєктів

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `AccountID` | Ні | Рядок | Номер криптовалютного гаманця клієнта / ID рахунку в платіжній системі / Номер рахунку онлайн банкінгу або біржі / ID грошового переказу / ID чека або ваучера. |`Jkf4j9LndJ4k520JkdnT52`|
| `Signature` | Ні | Рядок | Сигнатура валюти, що купується – буквено-цифрове позначення валюти, яке складається зі скороченої назви валюти/криптовалюти/платіжної системи та ін. (“XPYUAH”, “LTC”, “NMC”, “XRP”...), згідно з [класифікацією сигнатур валют](https://jsons.info/signatures/currencies). |`XPYUAH`|
| `Sum` | Ні | Рядок | Сума валюти операції обміну (кількість валюти, що купується). | `0.0025` |

### Приклад запиту

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

~~~md
{
"Account": "[e-mail]",
"Callback": {
"PaySuccess": {
"URL": "https://www.all4.shopping/payments/payment_success"
}
},
"CallBackURL": "https://www.all4.shopping/payments/xpay/callback",
"Currency": "UAH",
"Email": "[e-mail]",
"Exchange": "EUR",
"FirstName": "Ім'я",
"LastName": "Прізвище",
"MiddleName": "",
"MIDs": [
{
"Account": "IBAN",
"EDRPOU": "123",
"MFO": "AAAA",
"MID": "ID",
"PaymentInfo": [
{
"Caption": "Призначення",
"Value": "Оплата за замовлення №1 від 08 April 2024 клієнт ПІБ"
}
],
"Sum": 250
}
],
"Order": 124,
"PaymentInfo": [
{
"Caption": "Призначення",
"Value": "Оплата за товар №1 від 08 April 2024 від ПІБ"
}
],
"PaymentSum": 100,
"PayType": "13",
"Phone": "[phone]",
"Transaction": {
"DateTime": "20240408 16:43:21",
"TerminalID": "1",
"TransactionID": "bb61-55b500d61f25"
}
}
~~~
</details>
:::

:::success
<details>
<summary>Приклад запиту [10005]</summary>
<br>

~~~md
{
"Partner": {
"PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
"OperationType": 10005,
"Locale": ""
},
"Data": "{\"PayType\": \"7\", \"Phone\": \"380507801058\", \"Account\": \"9ae56a0e-56b5-11ed-8c77-0050560147f8\", \"PaymentSum\: \"33000\", \"Callback\": {\"PaySuccess\": \"https://solutions.sportlife.ua/banking/success_ru.html\"}, \"Service\": [{\"ServiceCode\": \"SL_8\", \"Sum\": \"33000\", \"Attributes\": {\"ServiceName\": {\"uk\": \"Kyiv Teremky; Sports and health services; 000785051\"}}}], \"TTL\": 900, \"CallBackURL\": \"https://solutions.sportlife.ua/Connect/hs/paymentStatus/xPayStatus\", \"Transaction\": {\"TransactionID\": \"9ae56a0e-56b5-11ed-8c77-0050560147f8\", \"TerminalID\": \"1\"}}",
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

## Відповідь

*Загальна інформація по формуванню структури відповіді наведена у розділі [“Загальна інформація по підключенню (API)”](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA?both#%D0%A1%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80%D0%B0-%D0%B2%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D1%96).*

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

Успішна відповідь на запит [10005] містить посилання у вигляді рядка з ім'ям "URI" у структурі "Data":

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `URI` |Так| Рядок | Посилання на платіжну сторінку (Checkout). |`https://stage-mapi.xpaydirect.com/uk/frame/widget/banner-payment`|
| `uuid` |Так| Рядок | Унікальний ідентифікатор, що зв'язує запити ["check"](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA) та ["pay"](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ). |`f3cd72b6-e1ea-406f-9b44-a9b93b401b7f`|

### Приклади відповідей

:::success
<details>
<summary>Операція проведена успішно</summary>
<br>

~~~md
{
"Code": 200,
"Message": "done!",
"Data": {
"OperationDate": "2023-02-28T15:28:14.539768+02:00",
"OperationID": 9490967,
"OperationStatus": 10,
"URI": "https://stage-mapi.xpaydirect.com/uk/frame/widget/banner-payment",
"uuid": "2cda0150-d6bc-4e21-9c96-f2210f20e56e"
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

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

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationID": 111,
"OperationStatus": 21,
"Reason": 3
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

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

:::info

Для тестування даного запиту застосовуйте параметри **Тестового Партнера**.
Див. деталі підключення у розділі: ["Параметри підключення Тестового Партнера"](https://hackmd.io/kGejjgk0QaiwfpoZFnTadA).

<details>
<summary>Тестовий запит</summary>
<br>

~~~md
{
"Partner": {
"PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
"OperationType": 10005,
"Locale": "UK"
},
"Data": "{\"uuid\": \"c97c2b5a-5795-4eb1-b821-093bf86b241e\", \"Transaction\":{\"TransactionID\":\"8dвd1faa43331wwfff351\",\"TerminalID\": \"1\",\"DateTime\":\"20201211 120111\"},\"PayType\":\"0\",\"Phone\":\"380277777777\",\"Email\":\"[e-mail]\",\"Account\":\"380277777777\",\"ClientIP\":\"89.68.252.11\",\"PanSuffix\":\"8888\",\"Currency\":\"UAH\",\"Exchange\":\"UAH\",\"Signature\":\"\",\"AccountID\":\"\",\"PaymentSum\":\"1000\",\"Sum\":\"1000\",\"FirstName\":\"Володимир\",\"LastName\":\"Зеленський\",\"MiddleName\":\"Олександрович\",\"BrowserFingerprint\":\"86a190af26de3a920c62ea19ba0df3a8\",\"RecipientCard\":{\"PAN\":\"8888888888888888\"},\"PaymentInfo\":[{\"Caption\":\"Призначення\",\"Value\":\"Оплатазапакети\"}],\"Service\":[{\"ServiceCode\":\"\",\"Sum\":\"\"}],\"Callback\":{\"PaySuccess\":{\"URL\":\"\"}},\"BillAttr\":{\"PayerAddress\":\"ВулицяПеремоги\"},\"TTL\":\"300\",\"CallBackURL\":\"https://partner.com/callback/xpay2\",\"AccountPayments\":[{\"Sum\":\"\",\"Purpose\":\"\",\"Account\":\"\",\"EDRPOU\":\"\",\"ID\":\"\",\"RecipientName\":\"\",\"SenderName\":\"\",\"IPN\":\"\"}],\"ticket\":[],\"Transaction\":{\"TransactionID\":\"8dвd1faa43331wwfff351\",\"TerminalID\":\"\",\"DateTime\":\"\"}}"
}
~~~
</details>

<details>
<summary>Очікувана відповідь</summary>
<br>

~~~md
{
"Code": 200,
"Message": "done!",
"Data": {
"OperationDate": "2023-02-28T15:28:14.539768+02:00",
"OperationID": 9490967,
"OperationStatus": 10,
"URI": "https://stage-mapi.xpaydirect.com/uk/frame/widget/banner-payment",
"uuid": "2cda0150-d6bc-4e21-9c96-f2210f20e56e"
},
"KeyAES": "",
"Sign": ""
}
~~~
</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)".

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

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

Всі операції та статуси їх обробки доступні в особистому кабінеті Партнера, або в реєстрі оплат, отриманому на наступний день операції на пошту Партнера.

Для запиту [10005] додатково реалізовано два стани обробки операції:
- **Користувач ще не почав сплачувати** (`"Reason":100051`),
- **Час очікування платежу сплинув** (`"Reason":100053`).

| Код відповіді | Повідом-лення | Статус `OperationStatus` | Причина `Reason` | Стан оплати |
|:-:|:-:|:-:|:-:|-|
| `102` | `Processing` | `7` | 100051 | Користувач не почав оплату. |
| `102` | `Processing` | `5` | будь-яка | Операція в обробці. |
| `200` | `Error` | `21` | 100053 | Час очікування платежу сплинув. |
| `200` | `Error` | `21` | будь-яка | Виникла помилка оплати. Див. опис у таблиці ["Коди причин відхилення операцій"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w#%D0%9A%D0%BE%D0%B4%D0%B8-%D0%BF%D1%80%D0%B8%D1%87%D0%B8%D0%BD-%D0%B2%D1%96%D0%B4%D1%85%D0%B8%D0%BB%D0%B5%D0%BD%D0%BD%D1%8F-%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D1%96%D0%B9-%E2%80%9CReason%E2%80%9D:~:text=%D0%A2%D0%B0%D0%BA-,%D0%9A%D0%BE%D0%B4%D0%B8%20%D0%BF%D1%80%D0%B8%D1%87%D0%B8%D0%BD%20%D0%B2%D1%96%D0%B4%D1%85%D0%B8%D0%BB%D0%B5%D0%BD%D0%BD%D1%8F%20%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D1%96%D0%B9%20%22Reason%22,-%22Reason%22). |
| `200` | `Ok` | `10` | відсутня | Обробка операції завершена. |

Див. деталі у розділі: ["Довідкові матеріали"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w).

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

[[check] Протокол двостадійної взаємодії](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)
[[pay/error/refund] Статус операції (CallBackURL)](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ)
[[auth] Оплата методом "Google/Apple Pay"](https://hackmd.io/M0Q6tH0CTy-oPCA5QuFFig)
[[20003] Отримання статусу операції](https://hackmd.io/fvd8btZLQXywluia6w5uxg)

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

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