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

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

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

Запит [20003] застосовується для отримання поточного статусу будь-якої операції у будь-який момент.

## Запит

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

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

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

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

~~~
{
"TransactionID": "",
"TerminalID": "",
"OperationID": ""
}
~~~
</details>
:::

| Параметр | Обов'яз-ковість | Тип | Опис |Приклад |
|:----:|:----:|:----:|----|:----:|
|`TransactionID`^1^|Так/Ні|Рядок|Унікальний ідентифікатор транзакції у системі Партнера, статус якої необхідно отримати.|`459132be0cbf58`|
|`TerminalID`^1^|Так/Ні|Рядок|Унікальний ідентифікатор терміналу у системі Партнера, за яким проводилась транзакція, статус якої необхідно отримати.|`1`|
|`OperationID`^1^|Так/Ні|Ціле|Унікальний ідентифікатор операції у системі Оператора, статус якої необхідно отримати.|`111`|

:::warning
^1^ **Запит [20003] можна надіслати в одному з двох варіантів:**
1. За параметром `OperationID` - у цьому випадку значення `TransactionID` та `TerminalID` передаються порожні.
**Або**
2. За парою значень `TransactionID` та `TerminalID` - у цьому випадку параметр `OperationID` не передається.
:::

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

Для отримання поточного статусу транзакції при [двостадійній взаємодії](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA) у запиті [20003] слід передати значення `TransactionID` та `TerminalID` операції [[10005]](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg?view). При цьому у відповіді буде передано статус обробки операції "pay", згідно таблиці “[Статус обробки операції](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)”.

## Відповідь

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

Успішна відповідь на запит [20003] містить структуру `OperationResponse` -> `Data`, у якій передаються дані про запитану операцію та статус обробки:

| Параметр | Обов'яз-ковість | Тип | Опис |Приклад|
|:----:|:----:|:----:|----|:----:|
|`OperationID`|Так|Ціле|Унікальний ідентифікатор операції у системі Оператора, статус якої отримується.|`111`|
|`OperationStatus`|Так|Ціле|Статус обробки операції, згідно таблиці "[Статус обробки операції](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`|
|`DateTime`|Ні|Рядок|Дата та час обробки операції. Формат: YYYYMMDD HH24:MM:SS.|`20220521 06:41:04`|
|`OperationType`|Ні|Рядок|Тип операції, статус якої отримується. Згідно таблиці "[Коди типів операцій “OperationType](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w#%D0%9A%D0%BE%D0%B4%D0%B8-%D1%82%D0%B8%D0%BF%D1%96%D0%B2-%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D1%96%D0%B9-%E2%80%9COperationType%E2%80%9D)”.|`10102`|
|`ExtraData`^2^|Ні|Структура|Структура даних, що передає додаткову інформацію по проведеній операції. Параметр застосовується лише для запиту [[10005]](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg).|Див. приклад нижче.|

^2^ Параметри структури **"ExtraData"**:

| Параметр | Обов'яз-ковість | Тип | Опис |Приклад|
|:----:|:----:|:----:|----|:----:|
| `OriginalSum` |Ні | Ціле | Сума операції у копійках, де 1грн.=>`100`.|`111`|
| `Refund` | Ні| Ціле | Сума успішних повернень у копійках. |`11`|
| `RestSum` |Ні| Ціле | Підсумкова сума операції у копійках: `RestSum`=`OriginalSum`–`Refund`.|`100` |
| `Bank` |Ні | Рядок | Найменування банку емітента картки. |`BankName`|
| `CardType` | Ні| Рядок | Міжнародна платіжна система. |`Visa`|
| `PAN` |Ні | Рядок | Замаскований номер картки. |`123456******1234` |
| `Currency` | Ні| Рядок | Код валюти списання – скорочене буквене позначення валюти, описане в стандарті [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)) (“UAH”, “GBP”, “USD” та ін.). |`UAH`|
| `TxnID` | Ні | Ціле | Унікальний ідентифікатор транзакції у системі Оператора. | `321455` |
| `TicketURL` | Ні | Рядок | URL-адреса для отримання файлу квитанції. |`https:\\server\ticket`|
| `AccountPayments`^3^ |Ні | Масив | Масив структур, що передається для отримання статусу по проведеним оплатам "Пакета послуг за реквізитами". Див. ["AccountPayments"](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg?view#%D0%9C%D0%B0%D1%81%D0%B8%D0%B2-%E2%80%9CAccountPayments%E2%80%9D) у запиті [10005]. | Див. приклад нижче.|

^3^ Параметри структури **"AccountPayments"**:

| Параметр | Обов'яз-ковість | Тип | Опис |Приклад|
|:----:|:----:|:----:|----|:----:|
|`ID`|Ні|Рядок|Унікальний ідентифікатор платежу, переданий у масиві ["AccountPayments"](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg?both#%D0%9C%D0%B0%D1%81%D0%B8%D0%B2-%D1%81%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80-%E2%80%9CAccountPayments%E2%80%9D) запиту [10005]. |`af1377`|
|`Status`|Ні|Ціле|Статус обробки платежу, згідно таблиці ["Статус обробки операції"](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`|

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

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

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationID": 17,
"OperationStatus": 10,
"OperationResponse": "{\"Code\":200,\"Message\":\"done\",\"Data\":{\"OperationID: 11\",\"OperationStatus: 10\",\"DateTime\":\"20180510 13:23:19\",\"OperationType\":10102},\"KeyAES\":\"\",\"Sign\":\"\"}"
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

:::success
<details>
<summary>Операція проведена успішно (дані з структурою "ExtraData")</summary>
<br>

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationID": 17,
"OperationStatus": 10,
"OperationResponse": "{\"Code\":200,\"Message\":\"done\",\"Data\":{\"OperationID: 11\",\"OperationStatus: 10\",\"DateTime\":\"20180510 13:23:19\",\"OperationType\":10102,\"ExtraData\":{\"OriginalSum\":111,\"Refund\":11,\"RestSum\":100,\"Bank\":\"BankName\",\"CardType\":\"visa\",\"Currency\":\"UAH\",\"PAN\":\"123456******1234\"}},\"KeyAES\":\"\",\"Sign\":\"\"}"
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

:::success
<details>
<summary>Операція завершена з помилкою</summary>
<br>

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationID": 17,
"OperationStatus": 10,
"OperationResponse": "{\"Code\":200,\"Data\":{\"OperationStatus\":21},\"Sign\":\"\",\"KeyAES\":\"\",\"Message\":\"refund operation 144377 fail: 3 - Parameters not matching\",\"OperationType\":30201},\"KeyAES\":\"\",\"Sign\":\"\"}"
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

:::success
<details>
<summary>Операція відхилена - передано невірні дані</summary>
<br>

~~~md
{
"Code": 400,
"Message": "Transaction not found",
"Data": {
"OperationID": 0,
"OperationStatus": 21
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

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

:::info

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

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

~~~md
{
"Partner": {
"PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
"OperationType": 20003
},
"Data": "{\"TransactionID\":\"0c5328f5-bda9-4376-b6a0-ca544fcb48fc\",\"TerminalID\":\"1\",\"OperationID\":\"\"}",
"KeyAES": "",
"Sign": ""
}
~~~
</details>

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

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationDate": "2023-04-05T15:05:55.912384+03:00",
"OperationID": 14318003,
"OperationResponse": "{\"Code\":200,\"Message\":\"\",\"Data\":{\"DateTime\":\"2023-03-20T16:03:46.857292+02:00\",\"OperationID\":9499592,\"OperationStatus\":21,\"OperationType\":10303,\"Sum\":35200},\"KeyAES\":\"\",\"Sign\":\"\"}",
"OperationStatus": 10
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

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

[[20001] Отримання балансу гаманця](https://hackmd.io/c-2sDICDRGeplJ-QL8bETw)
[[20002] Отримання виписки по гаманцю](https://hackmd.io/L9EeXtQYRDCQD_IhAPKhMw)
[[20004] Отримання квитанції по операції](https://hackmd.io/mOA9rZ_xSxWrNZxKzvZ5HQ)
[[20008] Отримання курсу валют](https://hackmd.io/inushlCxQa2f0MRgvVD7eg)
[[20009] Отримання ліміту по операції [10101]](https://hackmd.io/a_-XSuzvRvG9t9cU2yoUvg)
[[20110] Отримання даних карти](https://hackmd.io/zFCegCSASKKjGCmoJkTYmw)

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

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