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

# Checkout Integration by Structured Link

:::info
[TOC]
:::

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

## How Structured Link Checkout Works

1. Client places an order on the Partner's website and clicks the payment button (see the scheme below).
2. Partner creates a structured link to the payment page (URI1) in the form:
:::info
environment.url/uk/frame/widget/banner-payment?<payment parameters>
:::
3. Client is redirected to the payment form, that displays all the necessary payment attributes.
4. Client chooses a payment method (or fills the card details) and confirms the payment.
5. By the result, client is redirected to the payment results page, and Partner gets the Operator response about the payment status. See details in the section "[[pay/error/refund] Operation Status (CallBackURL)](https://hackmd.io/r0If47QcT-qyFuNvGEN2Wg)".

## Scheme of Checkout by Structured Link


## Short Link Formation

To get a short payment link (for example, for sending in SMS/Viber/Telegram/etc.), make a request using the "GET" method to the following URI:
:::info
environment.url/uk/frame/widget/banner-link?<payment parameters>
:::

The result is a response from Operator in the form of a JSON structure:

:::info
{"shorturl": "short link to payment page"}
:::

## Structured Link Builder

To create a structured link manually, use the builder by URI:

**Test environment**

https://stage-mapi.xpaydirect.com/en/sl/builder

**Product Environment**

https://mapi.xpaydirect.com/en/sl/builder

:::success
<details>
<summary>Example of structured link creation by builder</summary>
<br>

https://stage-mapi.xpaydirect.com/uk/sl/builder?pid=7380bc60-f656-4e51-8d4f-a354a9b68f21&acc=12345&sum=111&data={"Phone":"380671234567", "ClientIP":" 8.8.8.8", "FirstName":"Olexii", "LastName":"Bondar", "RegistryAttr":[{"Caption":"acc_id", "Value":1234}], "PaymentInfo":[{" Caption":"Address", "Value":"Bulvar Morskyi, 54"}, { "Caption":"P/Р", "Value":1234}],"Callback": {"PaySuccess": {"URL ": "http://google.com/"}}}
</details>
:::

## Formation of Parameters

:::warning
*Specifics:*

* All parameter names are case sensitive.
* 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.
:::

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `pid` | Yes | String | Additional token (do not confuse with Partner Token), provided additionally by the Operator to identify the Partner for each request. |`7380bc60-f656-4e51-8d4f-a354a9b68f21` |
| `acc` | No | String | Client identifier in the Partner system: phone, email or other custom value (ID). The parameter is transmitted to display on the client's payment form. | `380638754213` </br> or `12345`|
| `sum` | No | Integer | Payment sum in kopecks. The parameter is transmitted to display the sum on the payment form. The parameter can't be changed by the client, but can be provided if necessary. |1UAH=>`100`|
| `data`^1^ | No |Structure | Data structure that transmits additional information to complete the operation and display on the payment page. | `JHGHJGJS32KDKLJALKJ` |

:::warning
^1^ *Content of “data” is a JSON structure, compressed in GZIP format and encoded in base64. Parameters of the "data" structure are formed similarly to the "Data" structure of the request [[10005] Get Checkout Link](https://hackmd.io/qSkRHz6gRKmxNrWRwwrjqg)*.
:::

## Examples of Structured Link

:::success
<details>
<summary>Example of structured link</summary>
<br>

**enviroment.url/uk/frame/widget/banner-payment?pid=7380bc60-f656-4e51-8d4f-a354a9b68f21&acc=12345&sum=5000&data=JHGHJGJS32KDKLJALKJ**

where:
pid=7380bc60-f656-4e51-8d4f-a354a9b68f21,
acc=12345,
sum=5000,
data=JHGHJGJS32KDKLJALKJ - *JSON structure compressed in GZIP format and encoded in base64.*
</details>
:::

:::success
<details>
<summary>Example of pseudocode</summary>
<br>

~~~md
data = urlencode( base64( gzip( json_encode( {"atrr1": "abc", "atrr2": 123} ) ) ) )
~~~
*[Pseudocode is >>](https://en.wikipedia.org/wiki/Pseudocode)*
</details>
:::

:::success
<details>
<summary>Example of structured link in PHP</summary>
<br>

~~~md
$json = '{"Phone":"380671234567", "ClientIP":"8.8.8.8", "FirstName":"Olexiy", "LastName":"Bondar", "RegistryAttr":[{"Caption":" acc_id", "Value":1234}], "PaymentInfo":[{"Caption":"Address", "Value":"Bulvar Morskyi, 54"}, { "Caption":"P/Р", "Value ":1234}]}';
$gzdata = gzencode($json);
$data = urlencode(base64_encode($gzdata));
$url = 'environment.url/uk/frame/widget/banner-payment?pid=7380bc60-f656-4e51-8d4f-a354a9b68f21&acc=1234&data=' . $data;
~~~
</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.

See details in the section ["[check] Two-Step Interaction Protocol"](https://hackmd.io/XcDW0oOKRLyIho-DOpOHjA).

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

See details in the section "[[pay/error/refund] Operation Status (CallBackURL)](https://hackmd.io/r0If47QcT-qyFuNvGEN2Wg)".

:arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw)
:arrow_left: [Checkout](https://hackmd.io/B7V3CnG2QUKI6Qr820GHkA)

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

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