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

# Підключення до системи MTBMoney

:::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.xpay.com.ua:488/xpay

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

~~~
-----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/xpay

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

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

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

Для прийому оплати на рахунок Партнера застосовується запит [10005].

:::info
Переглянути повний опис запиту: [[10005] "Отримання посилання на платіжну сторінку"](https://hackmd.io/1okrbJtPTVCsl6b_lyt9bg).
:::

### Запит

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

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

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

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

| Параметр | Обов’яз-ковість | Тип | Опис |Приклад |
|:-:|:-:|:-:|-|:-:|
| `FirstName` | Ні | Рядок | Ім'я клієнта. |`Олег`|
| `MiddleName` | Ні | Рядок | По батькові клієнта. |`Михайлович`|
| `LastName` | Ні | Рядок | Прізвище клієнта. |`Подільський`|
| `Address` | Ні | Рядок | Білінгова адреса клієнта. |`456 Main Street`|
| `City` | Ні | Рядок | Місто клієнта. |`San Diego`|
| `CountryCode` | Ні | Рядок | Код країни клієнта (ISO CODES), згідно табл. "[Country Codes](https://countrycode.org/)". |`US`|
| `PostCode` | Ні | Рядок | Індекс клієнта. |`92126`|
| `State` | Ні | Рядок | Штат клієнта. |`California (CA)`|
| `PaymentSum` | Ні | Ціле | Сума оплати у копійках. Параметр передається для відображення суми оплати на платіжній сторінці. При заповненому полі - Оператор не здійснює запит "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)" для визначення суми оплати. |50грн.=>`5000`|
| `Order` | Ні | Рядок |Номер замовлення. |`1234А`|
| `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`|
| `Callback` | Ні | Структура | Складається з структури даних `PaySuccess` для обробки успішного платежу, де поле `URL` - адреса, на яку буде перенаправлений клієнт після завершення оплати. |`https://partner.com/payment_success`|
| `CallBackURL` | Ні | Рядок | Адреса Партнера, на яку виконуються запити "[check](https://hackmd.io/kk2x9Wx8QSe_vV11tA-KFA)" та "[pay / error / refund](https://hackmd.io/2x_MsqZIT6epfiqcQimFwQ)" для сповіщення про результати оплати. |`https://partner.com/callback`|
| `MIDs`^4^ | Ні | Масив | Масив, що передає дані для розщеплення прийнятого платежу на користь мерчантів. |Див. приклад нижче.|
| `PaymentInfo`^5^ | Ні | Масив | Параметр передається для відображення деталей платежу на сторінці оплати. |Див. приклад нижче.|
|`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.|

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

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `MID` |Так| Ціле | Ідентифікатор мерчанта в системі Оператора (Merchant ID), на який зараховуються кошти. |`111`|
| `Sum` |Так| Ціле | Сума платежу у копійках.|1грн.=>`100` |
| `PaymentInfo`^5^ | Ні | Масив | Параметр передається для відображення деталей платежу на сторінці оплати. |Див. приклад нижче.|
| `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` | Ні | Рядок | Назва одержувача. |`ТОВ "Ресурс"`|

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

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `Caption` |Так| Рядок | Опис додаткової інформації. |`Призначення`|
| `Value` |Так| Рядок | Додаткова інформація. |`Оплата за замовлення №1 від 08.04.2024 клієнт ПІБ`|

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

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

~~~md
{
"Account": "[e-mail]",
"Email": "[e-mail]",
"FirstName": "Ім'я",
"LastName": "Прізвище",
"MiddleName": "",
"Callback": {
"PaySuccess": {
"URL": "https://partner.com/payment_success"
}
},
"CallBackURL": "https://partner.com/callback",
"Currency": "UAH",
"Exchange": "EUR",
"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>
:::

### Відповідь

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

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

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

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

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

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationDate": "2024-04-08T17:43:22.40934+03:00",
"OperationID": 1,
"OperationStatus": 10,
"URI": "https://mapi.xpaydirect.com/en/frame/widget/93c4*****4-d52e-4e07-85fd-3****b6bd60",
"uuid": "93c4*****4-d52e-4e07-85fd-3****b6bd60"
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

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

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationID": 111,
"OperationStatus": 21,
"Reason": 3
},
"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)".

## Виплати

### Виплата на картку

Виплата на картку може проводитись по одному з двох сценаріїв:

**1. За один крок - "Payouts (one step)"** - в результаті надсилання запиту на проведення виплати [[10301/10311/103013] "Гаманець-карта"](https://hackmd.io/v5DKCslVSiGacRGLePCrOw) Партнер отримує відповідь про [статус операції](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w#%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-Code): успіх ("OperationStatus": 10) або помилку ("OperationStatus": 21/22).


:::info
Де: **Client** - клієнт Партнера, **APP** - мобільний додаток Партнера, **XPAY** - Оператор,
**PS** (Payment System) - платіжна система (Visa, Mastercard та ін.).
:::

**2. У два кроки - "Payouts (two steps)"** - в результаті надсилання запиту на проведення виплати [[10301/10311/103013] "Гаманець-карта"](https://hackmd.io/v5DKCslVSiGacRGLePCrOw) Партнер: а) отримує розрахунок суми списання (+комісії) у відповідній валюті; б) надсилає підтвердження/скасування операції по виплаті через надсилання запитів [[10001/10002]](https://hackmd.io/KRcEsWMkRtiV0T1_ISoUMA).


Розглянемо детальніше роботу двоетапної схеми **"Payouts (two steps)"**:

* Клієнт через додаток Партнера ініціює зарахування коштів на картку.
* Партнер надсилає запит [[20001](https://hackmd.io/c-2sDICDRGeplJ-QL8bETw)] до системи XPAY, щоб отримати доступний баланс гаманця для проведення виплати, та передає в нього ID гаманця для виплат (який можна отримати в Оператора на етапі інтеграції).
* Якщо сума залишку на гаманці Партнера достатня (*The balance is sufficient*) - Партнер надсилає запит на проведення виплати [[10301/10311/103013] "Гаманець-карта"](https://hackmd.io/v5DKCslVSiGacRGLePCrOw).
* Оператор розраховує та бронює суму списання (+комісію) у відповідній валюті (*Ammount+Fee in currency*).
* Додаток Партнера відображає клієнту загальну суму списання (*Withdrawal amount*).
* Клієнт а) підтверджує загальну суму списання (*Payment confirmation*) -> Партнер надсилає запит на підтвердження операції [[10001]](https://hackmd.io/KRcEsWMkRtiV0T1_ISoUMA) -> Платіжна система здійснює виплату (*Replenishment*); або б) скасовує загальну суму списання (*Payment cancellation or timeout*) -> Партнер надсилає запит на скасування операції [[10002]](https://hackmd.io/KRcEsWMkRtiV0T1_ISoUMA).
* В завершення - клієнту відображається результат підтвердження/скасування зарахування коштів на картку, а Партнер отримує відповідь від Оператора про [статус операції](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w#%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-Code): успіх (*"OperationStatus": 10*) або помилку (*"OperationStatus": 21/22*).

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

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

~~~md
{
"MIDs": [
{
"MID": "1258725",
"Sum": 403850
}
],
"Purpose": "Повернення коштiв",
"Transaction": {
"DateTime": "20240423 10:42:34",
"TerminalID": "1",
"TransactionID": "1610"
},
"TransferA2C": {
"Sum": 403850,
"LastName": "LastName",
"FirstName": "FirstName",
"RecipientCard": {
"IPN": "1111111111",
"PAN": "4441********3330",
"LastName": "LastName",
"FirstName": "FirstName",
"MiddleName": "MiddleName"
}
}
}
~~~
</details>
:::

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

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

~~~md
{
"Code": 200,
"Data": {
"result": "OK",
"OperationID": 2234,
"OperationDate": "2024-04-23T10:42:46.262885+03:00",
"OperationStatus": 10
},
"Sign": "",
"KeyAES": "",
"Message": ""
}
~~~
</details>
:::

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

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationID": 2234,
"OperationDate": "2024-04-23T10:42:46.262885+03:00",
"OperationStatus": 21,
"Reason": 3
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

### Виплата на IBAN

:::info
Для проведення виплати на IBAN, що використовується для CJ, застосовується запит: [[10303] "Гаманець-IBAN"](https://hackmd.io/QF_yny3cRpCuQdUZq7dpyA).
:::

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

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

~~~md
{
"Currency": "UAH",
"Email": null,
"Exchange": "UAH",
"Phone": null,
"Purpose": "CJ; Переказ коштів; payment of fees, bonuses, prizes, and other payments from non-residents of Ukraine abroad for the use of their works, inventions; реєстраційний номер фактичного платника BC1****73; код країни відправника 826",
"RecipientPerson": {
"Account": "UA093****94990",
"Address": "M****b",
"Birthday": null,
"Birthplace": null,
"City": "Zhytomyr",
"CountryCode": "UA",
"Email": null,
"FirstName": "Y***v",
"IPN": "3****6",
"LastName": "Z***k",
"MiddleName": "",
"Phone": null,
"PostCode": "1***2",
"State": ""
},
"Sender": {
"Account": null,
"ActualCountry": "124",
"Building": "-",
"City": "Vancouver",
"Country": "124",
"CountryResidence": null,
"EDRPOU": null,
"MFO": null,
"Name": "***a Inc",
"Street": "ds St, Suite "
},
"Sum": 68900,
"Transaction": {
"DateTime": "20240419 07:10:05",
"TerminalID": "0",
"TransactionID": "test12"
}
}
~~~
</details>
:::

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

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

~~~md
{
"Code": 200,
"Data": {
"result": "OK",
"OperationID": 2234,
"OperationDate": "2024-04-23T10:42:46.262885+03:00",
"OperationStatus": 10
},
"Sign": "",
"KeyAES": "",
"Message": ""
}
~~~
</details>
:::

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

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationID": 2234,
"OperationDate": "2024-04-23T10:42:46.262885+03:00",
"OperationStatus": 21,
"Reason": 3
},
"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).

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

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

### Тестове списання/зарахування на карту

Для тестування операцій списання/зарахування коштів під час розробки використовується "тестове середовище", при цьому реальне списання та зарахування не відбувається.

Тестове середовище: `https://stage-papi.xpay.com.ua:488/xpay`

Для виконання операції списання/зарахування необхідно вказати валідний номер картки. Після цього буде показано імітацію сторінки 3DS (тестову сторінку) з двома кнопками: для успішного та не успішного завершення операції. При цьому будуть викликані потрібні Callback-и та здійснені перенаправлення на необхідні сторінки.

Номер картки для отримання **успішної відповіді** по операції зарахування:
`8888888888888888`.

Номер картки для отримання **неуспішної відповіді** по операції зарахування:
`4000000000000010`.

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

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

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

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

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

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


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

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


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

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