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

# [90001/90002/90003/90004/90005] Підготовка операції

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

Процедура проведення операції **через термінал** формується з двох запитів:

|"OperationType" | Тип операції |
|----|----|
|`90001/90002/90003/90004/90005`|Підготовка операції.|
|`90000`|[Виконання операції](https://hackmd.io/FtHIJD2mSU-zmMZsFm5axQ).|

Внаслідок запиту підготовки операції виконується перевірка можливості зарахування коштів за вказаними реквізитами.

## Порядок надсилання запитів


## Запити підготовки операції

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

Запити підготовки будь-якої операції містять однаковий набір параметрів, що відрізняються лише значенням поля `Recipient` в залежності від типу операції. Тип операції передається у полі `OperationType`.

|OperationType | Тип операції | Recipient| Приклад |
|:----:|----|----|:----:|
|`90001`|Зарахування коштів на карту.| PAN картки (номер банківської карти).| `8888888888888888` |
|`90002`|Зарахування коштів на гаманець.|Ідентифікатор гаманця: телефон чи email. | `380679335544` |
|`90003`^1^|Зарахування коштів за реквізитами.|^1^ Структура, що передає дані реквізитів. |Див. приклад нижче.|
|`90004`^2^|Оплата комунальних послуг.| ^2^ Структура, що передає дані для оплати комунальних послуг. |Див. приклад нижче.|
|`90005`|Поповнення телефону. | Номер телефону у форматі: "380ххххххххх". |`380679335544`|

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

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

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

~~~
{
"Sum": ,
"Recipient": "",
"Email": "",
"Phone": "",
"Address": "",
"CashIn": [
{
"n": ,
"value":
}
],
"Transaction": {
"TransactionID": "",
"TerminalID": "",
"DateTime": ""
}
}
~~~
</details>
:::

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `Sum` |Ні|Ціле|Ймовірна сума операції у копійках. Параметр застосовується для перевірки можливості поповнення на зазначену суму. |1 грн.=>`100`|
|`Recipient`|Так|Рядок / Структура|Реквізити для зарахування коштів. Значенням поля формується в залежності від типу операції (див. вище).|`380679335544`|
| `Email` | Ні | Рядок | Email клієнта. |`[e-mail]`|
| `Phone` | Ні | Рядок | Телефон клієнта у форматі: "380ххххххххх". |`380679335544`|
| `Address` | Ні | Рядок | Адреса ПТКС (програмно-технічний комплекс самообслуговування). |`Хрещатик, 1`|
|`CashIn` |Ні|Масив|Масив структур, що передає покупюрний звіт (для ПТКС), де: `n` - номер внесеної купюри, `value` - номінал купюри. |`[{"n":1, "value":100}, {"n":2, "value":200}]`|
|`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.|

^1^ Параметри структури **"Recipient" для запиту [90003]** (зарахування коштів за реквізитами):

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

^2^ Параметри структури **"Recipient" для запиту [90004]** (оплата комунальних послуг):

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `SenderName` | Так | Рядок | ПІБ платника. |`Биков Василь Сергійович`|
| `Account` | Так | Рядок | Номер особового рахунку платника. |`№859485`|
| `Address` | Так | Рядок | Сплата за адресу. |`м.Київ, вул. Хрещатик, 1`|
| `Order` | Так | Рядок | Номер рахунку. |`№433`|
| `Contract` | Так | Рядок | Номер договору. |`№МВ-848`|
| `MID` | Так | Рядок | Ідентифікатор отримувача оплати. |`117`|
| `Phone` | Ні | Рядок | Телефон клієнта у форматі: “380ххххххххх” |`380679335544`|

## Відповідь

*Загальна інформація по формуванню структури відповіді наведена у розділі [“Загальна інформація по підключенню (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).*

:::warning
Ідентифікатор операції (значення `OperationID`, отримане у відповіді на запит) необхідно відобразити у чеку клієнту. Ідентифікатор буде використаний для аналізу спірних ситуацій.
:::

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

:::success
<details>
<summary>Підготовка проведена успішно</summary>
<br>

~~~md
{
"Code": 102,
"Message": "Done",
"Data": {
"OperationDate": "2018-12-25T14:48:10.977847+02:00",
"OperationID": 167813,
"OperationStatus": 7
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

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

~~~md
{
"Code": 400,
"Message": "Fail",
"Data": {
"OperationDate": "2018-12-25T14:48:10.977847+02:00",
"OperationID": 0,
"OperationStatus": 21
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

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

:::info

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

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

~~~md
{
"Partner": {
"PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
"OperationType": 90001
},
"Data": "{\"Sum\":19000,\"Recipient\":\"8888888888888888\",\"Email\":\"[e-mail]\",\"Phone\":\"380277777777\",\"Transaction\":{\"TransactionID\":\"0c5328f5-bda9-4376-b6a0-ca544fcb81fc\",\"TerminalID\":\"1\",\"DateTime\":\"2023042110:15:01\"}}",
"KeyAES": "",
"Sign": ""
}
~~~
</details>

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

~~~md
{
"Code": 200,
"Message": "Done",
"Data": {
"OperationID": 9508748,
"OperationStatus": 7,
"Sum": 19000
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>

<br>

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

~~~md
{
"Partner": {
"PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
"OperationType": 90000
},
"Data": "{\"OperationID\":9508748,\"Sum\":19000,\"Recipient\":\"8888888888888888\",\"Email\":\"[e-mail]\",\"Phone\":\"380277777777\",\"Transaction\":{\"TransactionID\":\"0c5328f5-bda9-4376-b6a0-ca544fcb82fc\",\"TerminalID\":\"1\",\"DateTime\":\"2023042110:15:01\"}}",
"KeyAES": "",
"Sign": ""
}
~~~
</details>

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

~~~md
{
"Code": 200,
"Message": "Done",
"Data": {
"OperationDate": "2023-04-21T11:34:33.481997+03:00",
"OperationID": 9508749,
"OperationStatus": 10,
"result": "OK"
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

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

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