Протокол для оплати комунальних послуг в 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> ~~~ { "Account": "", "Transaction": { "TransactionID": "", "TerminalID": "", "DateTime": "" } } ~~~ </details> ::: | Параметр | Обов’яз-ковість | Тип | Опис |Приклад | |:-:|:-:|:-:|-|:-:| |`Account`|Так|Рядок|Особовий рахунок клієнта. |`1367`| |`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.| :::success <details> <summary>Приклад структури "Data"</summary> ~~~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> ~~~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> ~~~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> ~~~ { "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> ~~~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> ~~~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> ~~~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> Телефон: +38 093 891 92 00 Email: info@xpay.com.ua Telegram: @xpaysupportbot </details>