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

# [check] Two-Step Interaction Protocol

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

## Usage

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.

In this case, the payment operation is executed in two steps:

1. Operator sends a "**check**" request to the Partner to check the data and validate client operation.
2. After the operation is completed, Operator sends a notification to the Partner about the operation status by one of the following requests: **"pay/error/refund"**, described in the section ["[pay/error/refund] Operation Status (CallBackURL)"](https://hackmd.io/r0If47QcT-qyFuNvGEN2Wg).

## Scheme of Two-Step Interaction Protocol


## Specifics of Request Formation

* The two-step interaction protocol is only used paying via Checkout by any integration method (see the section "[Checkout Integration Methods](https://hackmd.io/B7V3CnG2QUKI6Qr820GHkA#Checkout-Integration-Methods)").
* The request is executed to the URL (parameter `CallBackURL` of the `Data` structure), transmitted in the request [[10005]](https://hackmd.io/qSkRHz6gRKmxNrWRwwrjqg).
* The request is sent once, and if there is no response, an operation error notification comes.
* The request is sent by the "GET" method and in the form of a string.
* The sum is transmitted in kopecks (1 UAH corresponds to "100").
* The phone is transmitted in international format without the “+” character.
* The separator between parameters is the “&” character.

## The "check" Request

The following parameters are sent in the request:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `command` | Yes | String | Request type.|`check` |
| `txn_id` | Yes | String | Unique transaction identifier in the Operator system. | `321455` |
| `uuid` | Yes | String | Unique identifier linking "check" and "pay/error/refund" requests. | `f3cd72b6-e1ea-406f-9b44-a9b93b401b7f` |
| `account` | Yes | String | Unique client identifier in the Partner's system: phone or email. | `380638754213` |
| `sum` | Yes | Integer| Payment sum in kopecks. |1UAH=>`100`|
| `pay_type` | Yes | String | Type of payment method. See the table "[Payment Types](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg#Payment-Types)"). | `1` |
| `locale` | Yes | String | Locale (language) of the payment page (the same locale from the request [[10005]](https://hackmd.io/qSkRHz6gRKmxNrWRwwrjqg)). | `uk` |

:::success
<details>
<summary>Example of "check" request</summary>
<br>

https://partner.host/protocol?command=check&txn_id=321455&uuid=f3cd72b6-e1ea-406f-9b44-a9b93b401b7f&account=380638754213&sum=100&pay_type=1&locale=uk

</details>
:::

## Response to the "check" Request

To the "check" request, the Partner sends response as a JSON structure, formed from the following parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `txn_id` | Yes | String | Unique transaction identifier transmitted in the "check" request. | `321455` |
| `result` | Yes | String | Operation status. See the table “[Operation Status](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg#Operation-Status)”. | `10` |
| `message` | No | String | Text message with the result description. | `Ok` |
| `info` | Yes | Structure | Data structure transmits payment details (sum, etc.) to execute the operation and display it on the payment page. Structure parameters are given below. | See example below. |

### The "іnfo" Structure Parameters

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `client_name` | No | String | Client name. | `Kindratenko Genadiy Yosypovych` |
| `contract_number` | No | String | Order number in the Partner system. | `98-00FAV` |
| `max_sum`^1^ | Yes/No | String | Maximum allowable payment sum in kopecks. Can be changed by the client to a smaller one, but not a larger one. | 1UAH=>`100` |
| `fixed_sum`^1^ | Yes/No | String | Fixed payment sum in kopecks. Cannot be changed by the client. | 1UAH=>`100` |
| `float_sum`^1^ | Yes/No | String | Payment sum in kopecks, entered manually by the client. | 1UAH=>`100` |
| `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.).| `AUD` |
| `account`^2^ | No | Structure | Data for payment by details. Structure parameters are given below. | See example below.|

:::warning
^1^ One of the parameters `max_sum`, `fixed_sum` or `float_sum` is required and transmitted to **display the payment sum** on the payment page. When `PaymentSum` is filled in the request [[10005]](https://hackmd.io/qSkRHz6gRKmxNrWRwwrjqg), the Operator does not send a "check" request to check the payment sum.

^2^ The `account` parameter is used only for "[payment by details](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg#Payment-Types)" (`"PayType":"4"` or `"PayType":"5"`) to get the payment details.
:::

### The "account" Structure Parameters

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `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). |`34190717`|
| `Account` | Yes | String | Recipient IBAN (International Bank Account Number). | `UA4030034600000-26008010065101` |
| `MFO`| Yes | String | Recipient "[Bank Sort Code](https://en.wikipedia.org/wiki/Sort_code). | `305299` |
| `Purpose` | Yes | String | Payment purpose. | `Payment Order No. 543345` |
| `SenderName` | Yes | String | Sender full name. | `Dzyuba A.I.` |
| `RecipientName` | Yes | String | Recipient full name. | `Shevchenko T.G.` |

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

~~~md
{
"txn_id": "321455",
"result": "10",
"message": "Ok",
"info": {
"client_name": "Kindratenko Genadiy Yosypovych",
"contract_number": "98-00FAV",
"fixed_sum": "3189"
}
}
~~~
</details>
:::

## 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: [Checkout](https://hackmd.io/B7V3CnG2QUKI6Qr820GHkA)
:arrow_left: [[10005] Get Checkout Link](https://hackmd.io/qSkRHz6gRKmxNrWRwwrjqg)

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

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