[УКР](https://hackmd.io/mXbVmGydTseaR2el4IwJ_Q) | ENG
:arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw)

# MTBMoney System Integration

:::info
[TOC]
:::

## API Access Parameters

To integrate the Partner, call the XPAY API. To access the XPAY API, use your personal [Partner Token](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ#Partner-Token).

All Partner requests must be encrypted using the RSA algorithm ([RSA Keys](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ#RSA-Keys)).

To identify the request in the Partner and Operator systems, use ["Transaction" Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ#Transaction-Structure).

For system configuration and testing of API requests use the **test environment**:

:::info
Test environment URI:

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

Test environment key:

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

To operate in **product environment** use the following data:

:::info

Product environment URI:

https://papi.xpaydirect.com/xpay

Product environment key:

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

## Payment Acceptance

Use request [10005] to accept payment to the Partner's account.

:::info
See the complete request description: [[10005] "Get Checkout Link"](https://hackmd.io/qSkRHz6gRKmxNrWRwwrjqg).
:::

### Request

*See the description of the "Partner", "KeyAES" and "Sign" attributes in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)".*

**Data structure** for this operation is formed from the following parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `PayType` | No | String | Type of payment method: </br> `0` or `empty field` - direct debiting of funds from the client's card via c2a (card-to-account) or p2p (person-to-person) remittance; </br> `1` - payment via Internet acquiring gateway; </br> `2` - deferred payment^1^; </br> `3` - payment via another widget; </br> `4` - payment by details^2^; </br> `5` - deferred payment by details^1,2^; </br> `7` - bulk payment for services; </br> `12` - bulk payment for services by details; </br> `13` - payment to merchants' accounts (MIDs); </br> `20` - payment via Google/Apple Pay. </br> For details, see: "[Payment Types](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg?view#Payment-Type)". | `5` |

:::warning
^1^ Sending the requests for "deferred payment" (`"PayType":2` or `"PayType":5`), Partner additionally sends the request "[Confirm/Сancel Pre-Authorization](https://hackmd.io/CM0Mt9FATVS3cWkihWG_bA)". In the absence of confirmation, the debit will be automatically canceled (due to the period of time specified in the Partner contract).

^2^ Sending the requests for "payment by details" (`"PayType":4` or `"PayType":5`), in response, Operator sends a "check" request to get payment details (see section ["[check] Two-Step Interaction Protocol"](https://hackmd.io/XcDW0oOKRLyIho-DOpOHjA)).
:::

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Phone`^3^ | No | String | Client phone number in format: "380xxxxxxxxxxxx". |`380961000000`|
| `Email`^3^ | No | String | Client email. |`[e-mail]`|
| `Account`^3^ | No | String | Client ID in the Partner system: phone or email. While processing these data, the Operator can send a "[check](https://hackmd.io/XcDW0oOKRLyIho-DOpOHjA)" request to the Partner. |`380961000000`|

:::warning
^3^ If none of these parameters are transmitted in the request (`Phone`, `Email` or `Account`), the Operator sends a link to the client form to enter. After getting the data, a "[check](https://hackmd.io/XcDW0oOKRLyIho-DOpOHjA)" request is executed to check the payment details. Among the `Phone` and `Email` fields, `Phone` has a higher priority. If the request must be executed by email, it should be specified in the `Account` field.
:::

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `FirstName` | No | String | Client name. |`Oleg`|
| `MiddleName` | No | String | Client middle name. |`Mykhaylovich`|
| `LastName` | No | String | Client last name. |`Podilskyi`|
| `PaymentSum` | No | Integer| Payment sum in kopecks. Parameter is transmitted to display the payment sum on the payment page. If the field is filled in - the Operator does not request "[check](https://hackmd.io/XcDW0oOKRLyIho-DOpOHjA)" to check the payment sum. |50UAH=>`5000`|
| `Order` | No | String | Order number. |`1234A`|
| `Currency` | Yes - paying in a currency different from UAH | String | Currency *debit* code is an abbreviated currency designation described in the standard [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Non_ISO_4217_currencies) (“GBP”, “USD”, etc.). |`USD`|
| `Exchange` | Yes - paying in a currency different from UAH | String | Currency *credit* code is an abbreviated currency designation described in the standard [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Non_ISO_4217_currencies) (“GBP”, “USD”, etc.). |`GBP`|
| `Callback` | No | Structure | Parameter consists of a `PaySuccess` data structure for successful payment processing, where the field `URL` is the client's redirection URL after completing the payment. |`https://partner.com/payment_success`|
| `CallBackURL` | No | String | Partner's URL to which "[check](https://hackmd.io/XcDW0oOKRLyIho-DOpOHjA)" and "[pay/error/refund](https://hackmd.io/r0If47QcT-qyFuNvGEN2Wg)" requests are executed for notification of payment results. |`https://partner.com/callback`|
| `MIDs`^4^ | No | Array | Array is used to split the accepted payment in favor of the merchants. | See example below.|
| `PaymentInfo`^5^ | No | Array | Parameter is used to display payment details on the payment page. | See example below.|
|`Transaction`|Yes|Structure|Structure transmits transaction data. See section "[Transaction Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#2-Data)".|See example below.|

^4^ **"MIDs"** array parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `MID` |Yes| Integer | Merchant ID in the Operator system, to which funds are credited. |`111`|
| `Sum` | Yes |Integer | Payment sum in kopecks. |1UAH=>`100`|
| `PaymentInfo`^5^ | No | Array | Parameter is used to display payment details on the payment page. | See example below.|
| `Account` |No| String | Recipient current account or IBAN (international bank account number). | `UA4830529900000 26008031203677`|
|`EDRPOU`|No|String | Recipient ["EDRPOU"](https://uk.wikipedia.org/wiki/%D0%9A%D0%BE%D0%B4_%D0%84%D0%94%D0%A0%D0%9F%D0%9E%D0%A3) code.|`3505506226` |
| `MFO` |No |String | Recipient "[Bank Sort Code](https://en.wikipedia.org/wiki/Sort_code). |`305299`|
| `Name` | No | String | Recipient name. |`Resource LLC`|

^5^ **"PaymentInfo"** array parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Caption` |Yes| String | Description of payment information. |`Purpose`|
| `Value` |Yes| String | Payment іnformation. |`Order Payment No. 1 dated 08 April 2024, client NAME`|

#### Request Example

:::success
<details>
<summary>Example of Data structure</summary>
<br>

~~~md
{
"Account": "[e-mail]",
"Email": "[e-mail]",
"FirstName": "First Name",
"LastName": "Last Name",
"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": "Purpose",
"Value": "Order Payment No. 1 dated 08 April 2024, client NAME"
}
],
"Sum": 250
}
],
"Order": "124",
"PaymentInfo": [
{
"Caption": "Purpose",
"Value": "Order Payment No. 1 dated 08 April 2024, client NAME"
}
],
"PaymentSum": 100,
"PayType": "13",
"Phone": "[phone]",
"Transaction": {
"DateTime": "20240408 16:43:21",
"TerminalID": "1",
"TransactionID": "bb61-55b500d61f25"
}
}
~~~
</details>
:::

### Response

*See the general information on the response structure formation in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#Response-Structure)"*.

A successful response to request [10005] contains a link in string format with the name "URI" in the **"Data" structure**:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `URI` |Yes| String | Link to payment page (Checkout). |`https://stage-mapi.xpaydirect.com/uk/frame/widget/691fafc9-5d64-46b5-22ba-85ce61cc26be`|
| `uuid` |Yes| String | Unique identifier linking ["check"](https://hackmd.io/XcDW0oOKRLyIho-DOpOHjA) and ["pay"](https://hackmd.io/r0If47QcT-qyFuNvGEN2Wg) requests. |`f3cd72b6-e1ea-406f-9b44-a9b93b401b7f`|

#### Response Examples

:::success
<details>
<summary>Operation Successfully Completed</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>Operation Failed</summary>
<br>

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

### Two-Step Interaction Protocol

Two-step interaction protocol is used when the Partner's Checkout page requires client authorization (phone/email entry), and during data processing on the Operator side, there is a need to check payment details and/or payment sum.

For details, see: ["[check] Two-Step Interaction Protocol"](https://hackmd.io/XcDW0oOKRLyIho-DOpOsumHjA).

### Pay/Error/Refund Requests (CallBackURL)

The final step in the operation execution is the Partner notification about the **operation status** by one of the following requests:

* **"pay"** (payment completed),
* **"error"** (payment error),
* **"refund"** (refund done).

For details, see: "[[pay/error/refund] Operation Status (CallBackURL)](https://hackmd.io/r0If47QcT-qyFuNvGEN2Wg)".

## Payouts

### Payout to Card

Payout to the card can be made in one of two scenarios:

**1. Payouts in one step** - as a result of sending payout request [[10301/10311/103013] "Wallet-Card"](https://hackmd.io/SvLoAv49QWOIsdPhCWFezA) the Partner gets an [operation status](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg#Response-Code) response: success ("OperationStatus": 10) or error ("OperationStatus": 21/22).


:::info
Where: **Client** - Partner's client, **APP** - Partner's mobile application, **XPAY** - Operator,
**PS** - payment system (Visa, Mastercard, etc.).
:::

**2. Payouts in two steps** - as a result of sending payout request [[10301/10311/103013] "Wallet-Card"](https://hackmd.io/SvLoAv49QWOIsdPhCWFezA) the Partner a) gets a calculation of the withdrawal amount (+Fee) in the appropriate currency; b) sends confirmation/cancellation of the payout operation by sending requests [[10001/10002]](https://hackmd.io/GQcXQzGIRnmpnUW113fQGw).


Let's consider the two-step scheme **"Payouts (two steps)"** in more detail:

* Сlient initiates funds transfer to the card by using the Partner's application.
* Partner sends a request [[20001](https://hackmd.io/SVZQwSioRiGRiy0JwUQFWw)] to the XPAY system to get the available wallet balance for payout, and transmit Wallet ID for payouts (which can be got from Operator at the integration stage).
* If the Partner's wallet balance is sufficient (*The balance is sufficient*) - Partner sends a request for payout [[10301/10311/103013] "Wallet-Card"](https://hackmd.io/SvLoAv49QWOIsdPhCWFezA).
* Operator calculates and reserves the withdrawal amount (+Fee) in the appropriate currency (*Ammount+Fee in currency*).
* The Partner's application displays the total withdrawal amount to the client (*Withdrawal amount*).
* Client a) confirms the total withdrawal amount (*Payment confirmation*) -> Partner sends a request to confirm the operation [[10001]](https://hackmd.io/GQcXQzGIRnmpnUW113fQGw) -> Payment system executes payment (*Replenishment*); or b) cancels the total amount of withdrawal (*Payment cancellation or timeout*) -> Partner sends a request to cancel the operation [[10002]](https://hackmd.io/GQcXQzGIRnmpnUW113fQGw).
* At the end, the result of confirmation/cancellation of payout to the card is displayed to the client, and the Partner gets a response from Operator with the [operation status](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg#Response-Code): success ("OperationStatus": 10) or error ("OperationStatus": 21/22).

#### Request Example [103013]

:::success
<details>
<summary>Example of the "Data" structure</summary>
<br>

~~~md
{
"MIDs": [
{
"MID": "1258725",
"Sum": 403850
}
],
"Purpose": "Refund",
"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>
:::

#### Examples of Responses to the Request [103013]

:::success
<details>
<summary>Operation Successfully Completed</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>Operation Failed</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>
:::

### Payout to IBAN

:::info
To make a payout to the IBAN used for CJ, the request: [[10303] "Wallet-IBAN"](https://hackmd.io/7kfzI0OAQB6Nt8ZN38UxSg) is used.
:::

#### Request Example [10303]

:::success
<details>
<summary>Example of the "Data" structure</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>
:::

#### Examples of Responses to the Request [10303]

:::success
<details>
<summary>Operation Successfully Completed</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>Operation Failed</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>
:::

## Get Transaction Data

### Get Wallet Balance

:::info
To get the current wallet balance use the request: [[20001] Get Wallet Balance](https://hackmd.io/SVZQwSioRiGRiy0JwUQFWw).
:::

### Get Operation Status

All transactions and their processing statuses are available in the Partner's personal account, or in the payment register received by the Partner's mail on the next day of the transaction.

:::info
To get the current operation status use the request: [[20003] "Get Operation Status"](https://hackmd.io/_eAjmoG-QPWoWWmsLOGf1g).
:::

See the response codes and signs of fatality in the table ["Response Code"](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg#Response-Code).

Getting an HTTP code with **"no"** fatality, it is necessary to continue the operation in the Operator/Partner system.

To request the current operation status, repeat the request [[20003](https://hackmd.io/_eAjmoG-QPWoWWmsLOGf1g)] with previously sent parameters until getting the HTTP code with **"yes"** fatality. The operation status will be changed in the response.

:::warning
A repeat request can be sent to the Operator: **no more than once every 60 seconds**.
:::

The time for sending a **response** is limited to **55 seconds**. If the operation is not completed, the XPAY system generates a response with the code `102`.

:::warning
Getting a `timeout` for any API request, including a status request - must be treated as a response with code `102` and continue to request status until a fatal code is received.
:::

For request [10005], two operation processing states are additionally implemented:
- **User has not started payment** (`"Reason":100051`),
- **Payment time expired** (`"Reason":100053`).

| Response code | Message | Status `OperationStatus` | Reason | Payment status |
|:-:|:-:|:-:|:-:|-|
| `102` | `Processing` | `7` | 100051 | User has not started payment. |
| `102` | `Processing` | `5` | any | Operation in processing. |
| `200` | `Error` | `21` | 100053 |Payment time expired. |
| `200` | `Error` | `21` | any | Payment error. See description in the table ["Reason codes of Operation Rejection"](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg?view#:~:text=Yes-,Reason%20codes%20of%20Operation%20Rejection,-%22Reason%22). |
| `200` | `Ok` | `10` | missing | Operation processing is complete. |

For details, see: ["Reference Materials"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w).

## Test Procedure on Test Environment

:::info
**Test Partner** with all necessary permissions is created for testing any operations and getting acquainted with XPAY services. See details in the section: ["Test Partner Settings"](https://hackmd.io/1Ftkd9PVSvGBc9JV8f9b9A).
:::

## Test Procedure on Product Environment

To test operations on the production environment, check the correctness of at least four operations:

* by Visa;
* by MasterCard;
* Successful Operation;
* Failed Operation.

:::warning
For Successful Operations - check the availability and correctness of payment receipts.
For Successful/Failed Operations - check their display correctness in the Partner's cabinet.
In the case of sending Callbacks - check their getting and correct processing in the Partner's system.
:::

## Operations' View in Cabinet

To get complete information on transactions, follow the section ["Analytics"](https://xpay.notion.site/e0e8707a1cc34340b76d97fce25906c3?pvs=25) in Partner's cabinet.


## Get Register

The way, in which transaction registers will be formed is determined at the stage of Partner integration. By default (in cabinet or by email) Partner will get a register according to the template, or:

* from the XPAY Partner's cabinet;
* send the standard XPAY register to the email specified by the Partner;
* send the register to the email according to Partner template.

## Reference Materials

General parameters of the XPAY system are given in the section ["Reference Materials"](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg):  operation types, payment types, response codes, operation status, reasons of operation rejection, etc.

:arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw)
:arrow_left: [General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)

<details>
<summary>XPAY Support</summary>
</br>

Phone: [phone]
Email: [e-mail]
Telegram: @xpaysupportbot
</details>