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

# [10005] Get Checkout Link

:::info
[TOC]
:::

*What is Checkout, payment types and integration methods, see the section ["Checkout"](https://hackmd.io/B7V3CnG2QUKI6Qr820GHkA).*

:::warning
By default, the payment page is accessible for 15 minutes. If necessary, this period of time can be changed by `TTL` parameter of "Data" structure (see below) or set in the Operator system settings.
:::

## 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

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

:::info
<details>
<summary>Data structure formation (examples are below)</summary>
<br>

~~~
{
"PayType": "",
"Phone": "",
"Email": "",
"Account": "",
"FirstName": "",
"LastName": "",
"MiddleName": "",
"IPN": "",
"PaymentSum": ,
"Order": "",
"Purpose": "",
"ClientIP": "",
"PanSuffix": "",
"Currency": "",
"Exchnge": "",
"Signature": "",
"AccountID": "",
"Sum": "",
"BrowserFingerprint": "",
"RecipientCard": {
"PAN": "",
"FirstName": "",
"MiddleName": "",
"LastName": "",
"IPN": "",
"document_type_id": "",
"doc_series": "",
"doc_number": "",
"dt_doc_issue": "",
"dt_doc_exp": "",
"doc_issued_by": ""
},
"MIDs": [
{
"MID": ,
"Sum": ,
"PaymentInfo": [
{
"Caption": "",
"Value": ""
}
],
"Account": "",
"EDRPOU": "",
"MFO": "",
"Name": "",
"Order": ""
}
],
"PaymentInfo": [
{
"Caption": "",
"Value": ""
}
],
"RegistryAttr": [
{
"Caption": "",
"Value": ""
}
],
"Service": [
{
"ServiceCode": "",
"Sum":
}
],
"Callback": {
"PaySuccess": {
"URL": ""
},
"PayFail": {
"URL": ""
}
},
"BillAttr": {
"PayerAddress": ""
},
"TTL": "",
"CallBackURL": "",
"AccountPayments": [
{
"Sum": ,
"Purpose": "",
"Account": "",
"EDRPOU": "",
"ID": "",
"RecipientName": "",
"SenderName": "",
"IPN": ""
}
],
"ticket": [],
"cashiersignature": "",
"Transaction": {
"TransactionID": "",
"TerminalID": "",
"DateTime": ""
}
}
~~~
</details>
:::

|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". |`380679335544`|
| `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. |`380638754213`|

:::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`|
| `IPN` | Сonditionally mandatory (determined at the integration stage) | String | Payer individual tax number (IPN). |`111111111111`|
|`RecipientCard`^4^|No|Structure|Structure transmits the recipient's bank card data.|See example below.|
| `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`|
| `Purpose` |No| String | Purpose of payment. |`Payment of order No. 543345`|
| `ClientIP` | No | String | IP address from which the client initiates the operation. |`127.0.0.1`|
| `PanSuffix` | No | String | Last 4 digits of the card number, if the card has been previously verified. |`3456`|
| `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`|
| `BrowserFingerprint` | No | String |[Browser Fingerprint](https://en.wikipedia.org/wiki/Device_fingerprint): [https://m.habr.com/ru/company/oleg-bunin/blog/321294/](https://m.habr.com/ru/company/oleg-bunin/blog/321294/); [https://github.com/valve](https://github.com/valve) |`86a190af26de3a920c62ea19ba0df3a8`|
| `BillAttr` | No | Structure | Structure transmits the client return address: `PayerAddress`. |`m. Kharkiv, str. Chemists 4/59`|
| `Callback` | No | Structure | Parameter consists of 2 data structures: `PaySuccess` (successful payment processing) and `PayFail` (error processing), where the field `URL` is the client's redirection URL after completing the payment. |``"Callback": { "PaySuccess": { "URL": "https://partner.com/callback/success"}, "PayFail": {"URL": "https://partner.com/callback/fail"}}``|
| `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/xpay2`|
| `TTL` | No | Integer |Payment page accessibility time. Parameter is given in seconds. |`300`|
|`Transaction`|Yes|Structure|Structure transmits the transaction data. See section "[Transaction Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#2-Data)".|See example below.|

^4^ **"RecipientCard"** Structure Parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `PAN` | Yes | String[16] | Recipient card PAN (bank card number). | `8888888888888888` |
| `FirstName` | Yes* | String | Recipient name. |`Maxim` |
| `MiddleName` | Yes* | String | Recipient middle name. |`Olegovich`|
| `LastName` | Yes* | String | Recipient last name. |`Kravets`|
| `IPN` | Yes* | String | Recipient individual tax number (IPN). |`111111111111`|
| `document_type_id` | Yes* | Integer | Document type from the directory: </br> `1` - passport, </br> `2` - ID-card. |`1`|
| `doc_series` | Yes* | String | Document series. |`19910824-00026`|
| `doc_number` | Yes* | String | Document number. |`123456789`|
| `dt_doc_issue` | Yes* | String | Date of document issuance. |`2022-06-14`|
| `dt_doc_exp` | Yes* | String | Expiration date of the document. |`2022-06-14`|
| `doc_issued_by` | Yes* | String | Authority that issued the document. |`3459`|

**Parameters are conditionally mandatory (determined at the integration stage).*

</br>

Let's consider the parameters of the "Data" attribute with the **array structure**.

#### "MIDs" array

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `MIDs` | No | Array | Array is used to split the accepted payment in favor of the merchants. | See example below.|

**"MIDs"** array parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `MID` |Yes| Integer | Merchant ID in the Operator system. |`111`|
| `Sum` | Yes |Integer | Payment sum in kopecks. |1UAH=>`100`|
| `PaymentInfo` | 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`|
| `Order` | No | String | Recipient order number/personal account number/etc. |`123`|

:::success
<details>
<summary>Example of the "MIDs" data array</summary>

~~~md
{
"MIDs": [
{
"MID": 111,
"Sum": 100,
"PaymentInfo": [
{
"Caption": "Purpose",
"Value": "Contract Repayment No.3642989012-5 dated 04/03/2021 Pupkina Valeriya Serhiivna"
}
],
"Account": "UA483052990000000008031203000",
"EDRPOU": "3505501111",
"MFO": "123456"
},
{
"MID": 112,
"Sum": 200,
"PaymentInfo": [
{
"Caption": "Purpose",
"Value": "Contract Repayment No.3642989012-5 dated 04/03/2021 Pupkina Valeriya Serhiivna"
}
],
"Account": "UA483052990000000008031203000",
"EDRPOU": "3505501111",
"MFO": "123456"
}
]
}
~~~
</details>
:::

#### "PaymentInfo" Array

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `PaymentInfo` | No | Array | Parameter is used to display payment details on the payment page. | See example below.|

**"PaymentInfo"** array parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Caption` |Yes| String | Description of payment information. |`Purpose`|
| `Value` |Yes| String | Payment іnformation. |`Contract Repayment No. 3642989012-5 from 04/03/2021 Pupkina Valeriya Serhiivna`|

:::success
<details>
<summary>Example of the "PaymentInfo" data array</summary>
<br>
The payment page must display:
<br>
"Purpose: Contract Repayment No. 3642989012-5 from 04/03/2021 Pupkina Valeriya Serhiivna"

~~~md
{
"PaymentInfo": [
{
"Caption": "Purpose",
"Value": "Contract Repayment No. 3642989012-5 from 04/03/2021 Pupkina Valeriya Serhiivna"
}
]
}
~~~
</details>
:::

#### "RegistryAttr" Array

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `RegistryAttr` | No | Array | Parameter is used to generate and send Partner reports. | See example below.|

**"RegistryAttr"** array parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Caption` |Yes| String | Field name displayed in the reporting file. |`acc_id`|
| `Value` |Yes| String | Field value displayed in the reporting file.|`123`|

:::success
<details>
<summary>Example of the "RegistryAttr" data array</summary>

~~~md
{
"RegistryAttr": [
{
"Caption": "acc_id",
"Value": "123"
},
{
"Caption": "mdf_id",
"Value": "11011"
}
]
}
~~~
</details>
:::

#### "Service" Array

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Service`^5^ | No | Array `ServiceItem` | Parameter is used to pay for the service packet. Each payment contains service code and service payment sum. | See example below.|

:::warning
^5^ Parameter is used only sending the request for [bulk payment for services](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg#Payment-Types) (`"PayType":"7"`). Client's payment is split into several recipients, and funds are credited to pre-registered wallets.
:::

**"ServiceItem"** array parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `ServiceCode` | Yes |String | Alphanumeric service name or its provider. List of these values is individual and formed depending on the Partner's services.|`TEPLO`|
| `Sum` | Yes |Integer | Payment sum for the service in kopecks. |1UAH=>`100`|

:::success
<details>
<summary>Example of the "ServiceItem" data array</summary>
<br>

~~~md
{
"Service": [
{
"ServiceCode": "TEPLO",
"Sum": 5500
},
{
"ServiceCode": "GAZ",
"Sum": 12000
}
]
}
~~~
</details>
:::

#### "AccountPayments" Array

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `AccountPayments`^6^ | No | Array `AccountPayment` | Parameter is used to pay for the service packet by details. Each payment contains a set of parameters listed below.|See example below.|

:::warning
^6^ Parameter is used only sending the request for [bulk payment for services by details](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg#Payment-Types) (`"PayType":"12"`). The client's payment is split into several recipients, and funds are credited to the specified details.
:::

**"AccountPayments"** array parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Sum` |Yes| Integer | Payment sum for the service in kopecks. | 1UAH=>`100` |
| `Purpose` |Yes| String | Payment purpose. |`Payment Order No. 543345`|
| `Account` |Yes| String | Recipient IBAN (International Bank Account Number). | `UA173052990000026207893720887`|
| `EDRPOU` |Yes| 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. | `34190717` |
| `ID` |Yes| String | Unique payment identifier. |`af1377`|
| `RecipientName` |Yes| String | Recipient full name. |`Shevchenko T.G.`|
| `SenderName` |Yes| String| Sender full name. |`Dzyuba A.I.`|
| `IPN` |Yes| String | Individual income tax number. |`7845325697`|

:::success
<details>
<summary>Example of the "AccountPayment" data array</summary>
<br>

~~~md
{
"AccountPayments": [
{
"Sum": 10000,
"Purpose": "Payment Order #543345",
"Account": "UA173052990000026207893720887",
"EDRPOU": "34190717",
"ID": "af1377",
"RecipientName": "Shevchenko T.G.",
"SenderName": "Dzyuba A.I.",
"IPN": "7845325697"
},
{
"Sum": 20000,
"Purpose": "Payment Order #543000",
"Account": "UA173052990000026207893765656",
"EDRPOU": "33230717",
"ID": "af12277",
"RecipientName": "Mulyar O.V.",
"SenderName": "Dzyuba A.I.",
"IPN": "7845325697"
}
]
}
~~~
</details>
:::

#### "Ticket" Array

The `ticket` parameter is used to generate a **fiscal check** at the software cash register.

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `ticket`^7^ | No | Array `ticket` | Parameter transmits the product information: product ID, name, cost and quantity. | See example below. |
| `cashiersignature` | No | String | Cashier signature. Parameter is used only for operation fiscalization and formation of "[РРО](https://tax.gov.ua/baneryi/programni-rro/aktualni-zapitannya-vidpovidi/)" receipts (Eng. [Registrar of Settlement Operations, RSO](https://uk.wikipedia.org/wiki/%D0%A0%D0%B5%D1%94%D1%81%D1%82%D1%80%D0%B0%D1%82%D0%BE%D1%80_%D1%80%D0%BE%D0%B7%D1%80%D0%B0%D1%85%D1%83%D0%BD%D0%BA%D0%BE%D0%B2%D0%B8%D1%85_%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D1%96%D0%B9)). | `nvfjdjjfdjdkjf84iewjd` |

:::warning
^7^ **Check fiscalization:**
1. Partner registers on the resource: checkbox.ua (with registration of "РРО" and cashier).
2. In the "checkbox" cabinet Partner independently manages: the opening/closing shifts and reporting (X, Z).
3. In the request by the `ticket` parameter, the Partner transmits data to the Operator for the fiscal check registration.
4. Using the request data, the Operator checks whether the transaction sum matches the sum of goods in the check.
5. Operator fiscalizes the check through the resource: checkbox.ua.
6. In conclusion - Operator sends the payer a link to the "РРО" check to email or sms (by agreement).

**To register a check, the Partner need to:**

1. Give the Operator the cashier login/password,
OR
2. Form a cashier signature (`cashiersignature`) in each request.
:::

**"Ticket"** array parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `ID` |Yes|String|Product identifier.|`11`|
| `Good` |Yes|String|Product name.|`bolt`|
| `Price` |Yes| Integer| Product price in kopecks. |1UAH=>`100` |
| `Count` |Yes| Integer | Product quantity. |1pc.=>`1000`</br> 2.25kg=>`2250`|
| `uktzed` |No|String|Digital product code according to ["УКТ ЗЕД"](https://uk.wikipedia.org/wiki/%D0%A3%D0%BA%D1%80%D0%B0%D1%97%D0%BD%D1%81%D1%8C%D0%BA%D0%B0_%D0%BA%D0%BB%D0%B0%D1%81%D0%B8%D1%84%D1%96%D0%BA%D0%B0%D1%86%D1%96%D1%8F_%D1%82%D0%BE%D0%B2%D0%B0%D1%80%D1%96%D0%B2_%D0%B7%D0%BE%D0%B2%D0%BD%D1%96%D1%88%D0%BD%D1%8C%D0%BE%D0%B5%D0%BA%D0%BE%D0%BD%D0%BE%D0%BC%D1%96%D1%87%D0%BD%D0%BE%D1%97_%D0%B4%D1%96%D1%8F%D0%BB%D1%8C%D0%BD%D0%BE%D1%81%D1%82%D1%96) (Eng. Ukrainian Classification of Foreign Trade Goods).|`0403`|

:::success
<details>
<summary>Example of the "ticket" data array</summary>
<br>

~~~md
{
"ticket": [
{
"ID": "11",
"Good": "bolt",
"Price": 100,
"Count": 1000
},
{
"ID": "22",
"Good": "vtulka",
"Price": 2500,
"Count": 60000
}
]
}
~~~
</details>
:::

#### Crypto Project Parameters

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `AccountID` | No | String | Customer cryptocurrency wallet number / Payment system account ID / Account number of online banking or exchange / Money transfer ID / Check or voucher ID. |`Jkf4j9LndJ4k520JkdnT52`|
| `Signature` | No | String | Purchased сurrency signature is an alphanumeric currency designation, that consists of a shortened currency name/cryptocurrency/payment system, etc. (“XPYUAH”, “LTC”, “NMC”, “XRP”...), according to [Currency Signature Classification](https://jsons.info/en/signatures/currencies). |`XPYUAH`|
| `Sum` | No | String | Currency sum of the exchange transaction (amount of currency being purchased). | `0.0025` |

### 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://www.all4.shopping/payments/payment_success"
}
},
"CallBackURL": "https://www.all4.shopping/payments/xpay/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>
:::

:::success
<details>
<summary>Example of the request [10005] </summary>
<br>

~~~md
{
"Partner": {
"PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
"OperationType": 10005,
"Locale": ""
},
"Data": "{\"PayType\": \"7\", \"Phone\": \"380507801058\", \"Account\": \"9ae56a0e-56b5-11ed-8c77-0050560147f8\", \"PaymentSum\: \"33000\", \"Callback\": {\"PaySuccess\": \"https://solutions.sportlife.ua/banking/success_ru.html\"}, \"Service\": [{\"ServiceCode\": \"SL_8\", \"Sum\": \"33000\", \"Attributes\": {\"ServiceName\": {\"uk\": \"Kyiv Teremky; Sports and health services; 000785051\"}}}], \"TTL\": 900, \"CallBackURL\": \"https://solutions.sportlife.ua/Connect/hs/paymentStatus/xPayStatus\", \"Transaction\": {\"TransactionID\": \"9ae56a0e-56b5-11ed-8c77-0050560147f8\", \"TerminalID\": \"1\"}}",
"KeyAES": "",
"Sign": ""
}
~~~
</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)"*.

### Data 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/banner-payment`|
| `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)".

## Get Operation Status

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

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.

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).

## Testing Procedure

:::warning
**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).
:::

## Related Requests

[[check] Two-Step Interaction Protocol](https://hackmd.io/XcDW0oOKRLyIho-DOpOHjA)
[[pay/error/refund] Operation Status (CallBackURL)](https://hackmd.io/r0If47QcT-qyFuNvGEN2Wg)
[[auth] Google/Apple Pay](https://hackmd.io/_NXWjnOgRfe60YctuLtIAQ)
[[20003] Get Operation Status](https://hackmd.io/_eAjmoG-QPWoWWmsLOGf1g)

## 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>