---
# System prepended metadata

title: Протокол для оплати комунальних послуг в POS-терміналі

---

# Протокол для оплати комунальних послуг в POS-терміналі

:::info
[TOC]
:::

## Підключення до API

Підключення Партнера виконується методом виклику API XPAY. Для звернення до API XPAY використовується персональний [токен Партнера](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA?both#%D0%A2%D0%BE%D0%BA%D0%B5%D0%BD-%D0%9F%D0%B0%D1%80%D1%82%D0%BD%D0%B5%D1%80%D0%B0).

Всі запити Партнера мають бути закриптовані з використанням алгоритму RSA ([ключі RSA](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA?both#RSA-%D0%BA%D0%BB%D1%8E%D1%87%D1%96)).

Для ідентифікації запиту в системах Партнера та Оператора необхідно використовувати [структуру "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA?view#%D0%A1%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80%D0%B0-Transaction). 

Налаштування системи та тестові запити API  виконуються на **тестовому середовищі**:
 
:::info
Адреса тестового середовища:

```
https://stage-papi.xpaydirect.com
```

Ключ для тестового середовища:

~~~
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0IH2V0Ot1ej4FdOihujG
ON37sqql62vFFR/4IK+w4xqHRvD+SEwwkLL9EO72e42bV9VaKOqKbX81A+0hbBXi
W7axjHU2Sc97EXTHjpwX++HduUXbXhRteyzcHDLZCGKT8WzoNgQeXcieLUYUp2bb
gjElGecKprcprkMeHmffmelwlzcv61auGU0o10CTyyCqhOKofdqJq6A2KOBCLL49
5z1700oCRo9qL4loe95r4wGh6AmHZNvAnAwLgzwzyLvWCz479CVIWEaMY/+uczfL
0yRjN+8uqNK3A09wOD+wO1I+YfU9YXcQ75L8ibxzWcNgMHrhJQ9ZtnoVltiTWEEB
9QIDAQAB
-----END PUBLIC KEY-----
~~~
:::

Для роботи на **продуктовому середовищі** необхідно застосувати наступні дані:

:::info

Адреса продуктового середовища:
```
https://papi.xpaydirect.com
```

Ключ для продуктового середовища:

~~~
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA9+1AEFfD9MoO0IWeMk3f    
aFoYBBekFgHmUGM48AVh6BW/s5r16mtUfMfRfezVgqluwV/liEd6hArmmEZIKwYE    
mJoAYuY/ny9QJpc8zY+toR5IJEtYxfStHmVwKSuvHL3KY/U/Ok5UUT2u075JPZb+
FtDZwW9KXkwmT53HQ6iS0XFyy621vGrs6XcdGwO6eZPptkvc8SYKDwClgLjI69Iz
b6K/dfdQUioMPvZOXpdzrEQXjnipmsYh1VxOufqsX1SDzqR67Zs114OnHWAZhTXE
ksUjKavJkCc07T+nu1O/r99rsrRCaQODVq8SMAoK1vxJLf29WFv4ydp4vIk+n98/
DQIDAQAB
-----END PUBLIC KEY-----
~~~
:::


## Приймання оплати


### Запит [check]

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

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

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

~~~
{
    "Account": "",
    "Transaction": {
        "TransactionID": "",
        "TerminalID": "",
        "DateTime": ""
    }
}
~~~
</details>
:::


| Параметр | Обов’яз-ковість | Тип | Опис |Приклад |
|:-:|:-:|:-:|-|:-:|
|`Account`|Так|Рядок|Особовий рахунок клієнта. |`1367`|
|`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.|


:::success
<details>
<summary>Приклад структури "Data"</summary>
<br>
    
~~~md
{
    "Account": "1367",
    "Transaction": {
        "TerminalID": "1",
        "TransactionID": "3185518941"
    }
}
~~~
</details>
:::



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

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


У відповідь на запит [check] Партнер отримує **структуру та суму по заборгованості клієнта** для виведення даних на сторінку оплати.

Параметри структури **"Services"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
|`account`| Так |Рядок| Унікальний ідентифікатор клієнта у системі Оператора. |`be05fc0-45c4-4b49-9a02-3fa450cb1a4e`|
| `bill_attr`^1^ | Так | Масив | Масив, що передає деталі платежу для відображення на сторінці оплати. |Див. приклад нижче.|
| `bills`^2^ | Так | Масив | Масив, що передає дані про позицію рахунку на оплату для відображення на сторінці оплати. |Див. приклад нижче.|
|`hint`| Так |Рядок| Відображення підказки на сторінці оплати. |`Виберіть послугу`|
|`title`| Так |Рядок| Відображення найменування послуги на сторінці оплати. |`Послуга`|


^1^ Параметри масиву **"bill_attr"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `caption` |Так| Рядок | Опис додаткової інформації. |`ПІБ`|
| `value` |Так| Рядок | Додаткова інформація. |`МУСІЄНКО ОЛЕГ СЕРГІЙОВИЧ`|


^2^ Параметри масиву **"bills"**:

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
|`Counters`| Так |Структура | Структура, що передає дані лічильника через структуру `currentValue`^3^.|Див. нижче.|
| `fixed_sum` | Передається `fixed_sum` або `float_sum`. | Ціле | Фіксована сума платежу у копійках. Не може бути змінена клієнтом. | 1 грн.->`100` |
| `float_sum` | Передається `fixed_sum` або `float_sum`. | Ціле | Сума платежу у копійках, введена клієнтом вручну. | 1 грн.->`100` |
| `id` | Так | Ціле | Унікальний ідентифікатор рахунку, що передається в запит [pay]. |`117033032`|
| `ServiceCode` | Так | Рядок | Буквено-цифрова назва послуги або її постачальника. Перелік даних значень є індивідуальним та визначається в залежності від послуг, що надаються Партнером.|`WATER_INFOX01`|
|`title`| Так |Рядок| Найменування послуги. |`За водокористування. Населення на прямих розрахунках`|


^3^ Параметри cтруктури **"currentValue"**:

| Параметр | Обов'яз-ковість | Тип | Опис | Приклад|
|:-:|:-:|:-:|-|:-:|
| `required` | Так | Булевий | Обов'язковість параметру: `true`/`false`. |`false`|
| `step` | Так | Ціле | Порядковий номер лічильника. |`1`|
|`title`| Так |Рядок| Найменування послуги. |`Поточні показники лічильника води`|


#### Приклади відповідей на запит [check]

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

~~~md
{
  "Code": 200,
  "Data": {
    "OperationDate": "2024-10-31T14:19:17.255965+02:00",
    "OperationID": 374315530,
    "OperationStatus": 10,
    "Services": {
      "account": "be05f0-45c4-4b49-9a02-3fa450cb1a4e",
      "bill_attr": [
        {
          "caption": "Особовий рахунок",
          "value": "1367"
        },
        {
          "caption": "ПІБ",
          "value": "МУСІЄНКО ОЛЕГ СЕРГІЙОВИЧ"
        },
        {
          "caption": "Адреса платника",
          "value": "ВІННИЦЯ, ВУЛ.КЕЛЕЦЬКА, 41 кв.-"
        }
      ],
      "bills": [
        {
          "Counters": {
            "currentValue": {
              "required": false,
              "step": 1,
              "title": "Поточні показники лічильника води"
            }
          },
          "float_sum": 22625,
          "id": 117033032,
          "ServiceCode": "WATER_INFOX01",
          "title": "За водокористування. Населення на прямих розрахунках"
        }
      ],
      "hint": "Виберіть послугу",
      "title": "Послуга"
    }
  },
  "Message": "operation ok",
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::


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

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


### Запит [pay]

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

Після проведення оплати та списання коштів - Партнеру необхідно надіслати запит [pay] з наступними параметрами структури **"Data"**:


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

~~~
{
  "TransferC2W": {
    "Sum": 
  },
  "Bills": [
    {
      "ID": ,
      "Sum": 
    }
  ],
  "Transaction": {
    "TransactionID": "",
    "TerminalID": "",
    "DateTime": ""
  }
}
~~~
</details>
:::


| Параметр | Обов’яз-ковість | Тип | Опис |Приклад |
|:-:|:-:|:-:|-|:-:|
|`TransferC2W`| Так | Структура |Структура, що передає загальну суму операції: `Sum`.| Див. нижче.|
| `Bills` | Так | Масив | Масив, що передає дані операції: унікальний ідентифікатор платника послуг`ID`, отриманий у відповіді на запит [check], та сума операції `Sum`. |Див. приклад нижче.|
|`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.|


:::success
<details>
<summary>Приклад структури "Data"</summary>
<br>
    
~~~md
{
  "TransferC2W": {
    "Sum": 22625
  },
  "Bills": [
    {
      "ID": 117033032,
      "Sum": 22625
    }
  ],
  "Transaction": {
    "TerminalID": "1",
    "TransactionID": "be0c5fc0-45c4-4b49-9a02-3fa450cb1a4e"
  }
}
~~~
</details>
:::


### Відповідь на запит [pay]

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


#### Приклади відповідей на запит [pay]

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

~~~md
{
  "Code": 200,
  "Message": "Done",
  "Data": {
    "OperationDate": "2024-12-25T14:48:10.977847+02:00",
    "OperationID": 167818,
    "OperationStatus": 10
  },
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::

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

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


## Отримання даних по проведеній операції

### Перевірка балансу гаманця

:::info
Для отримання поточного балансу гаманця застосовується запит: [[20001] "Отримання балансу гаманця"](https://hackmd.io/c-2sDICDRGeplJ-QL8bETw). 
:::

### Перевірка статусу операції

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

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

Коди відповідей та ознаки фатальності див. у таблиці: ["Коди відповідей Оператора "Code"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w?view#%D0%9A%D0%BE%D0%B4%D0%B8-%D0%B2%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D0%B5%D0%B9-%D0%9E%D0%BF%D0%B5%D1%80%D0%B0%D1%82%D0%BE%D1%80%D0%B0-%E2%80%9CCode%E2%80%9D).

Отримання http-коду з ознакою фатальності **"ні"** передбачає продовження виконання операції у системі Оператора чи Партнера. 

Для запиту поточного статусу обробки операції  необхідно повторювати запит [[20003]](https://hackmd.io/fvd8btZLQXywluia6w5uxg) з надісланими раніше параметрами до отримання http-коду з ознакою фатальності **“так”**. У відповіді змінюватиметься статус проведення операції.

:::warning
Надсилання повторного запиту Оператору здійснюється: **не частіше 1-го разу за 60 сек**.
:::

Час на надсилання **відповіді** обмежений та складає **55 сек**. Якщо обробка операції не завершена - система XPAY формує відповідь з кодом `102`. 

:::warning
Отримання `timeout` на будь-який API запит, в тому числі на запит статусу - необхідно розцінювати, як відповідь з кодом `102` та продовжувати запитувати статус до отримання фатального коду.
:::

Для запиту [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).


## Порядок тестування на тестовому середовищі

![](https://i.imgur.com/gtxKB22.png)
:::info
Для тестування будь-яких операцій та ознайомлення з сервісами системи XPAY заведено **Тестового Партнера**. Див. деталі підключення у розділі: ["Параметри підключення Тестового Партнера"](https://hackmd.io/kGejjgk0QaiwfpoZFnTadA).
:::



## Порядок тестування на продуктовому середовищі

Для тестування операцій на продуктовому середовищі необхідно перевірити коректність виконання, як мінімум, чотирьох операцій:

* з карткою Visa;
* з карткою MasterCard;
* успішну;
* не успішну.

:::warning
По "успішним" операціям необхідно перевірити наявність та коректність квитанцій про оплату. По "успішним/не успішним" - перевірити коректність їх відображення в кабінеті Партнера. За наявності надсилання "колбеків" - перевірити надходження та коректне їх опрацювання в системі Партнера.
:::


## Перегляд транзакцій в кабінеті 

Щоб отримати повну інформацію по проведеним операціям необхідно в кабінеті Партнера перейти до розділу ["Аналітика"](https://xpay.notion.site/e0e8707a1cc34340b76d97fce25906c3?pvs=25).

![image](https://hackmd.io/_uploads/ByCG9XNeA.png)



## Отримання реєстру

Спосіб, у який будуть формуватися реєстри по операціям, визначається на етапі інтеграції Партнера:

![image](https://hackmd.io/_uploads/SkmN5-4l0.png)



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

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


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

Телефон: +38 093 891 92 00
Email: info@xpay.com.ua
Telegram: @xpaysupportbot
</details>
