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

# [pay/error/refund] Operation Status (CallBackURL)

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

## Partner Notifications

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 the general operation scheme in the "[API Checkout Integration](https://hackmd.io/dGsFmNB9T5mxDec-z6Sz8g)" section.

## Specifics of Request Formation

* The request is only executed 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 three times every 20 seconds until the Partner receives a response. If there is no response, a notification will be sent every 10 minutes until a response is received.
* 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 "pay/error" Request

The following parameters are sent in the request:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `command` | Yes | String | Operation status: </br> - "pay" - payment completed, </br> - "error" - payment error.|`pay` or `error` |
| `txn_id` | Yes | String | Unique transaction identifier in the Operator system. Getting a "pay" request with the `txn_id` parameter, that was previously transmitted - the request should be considered repeated, and a new transaction should not be generated. | `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 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` |
| `txn_date` |Yes|String| Date and time of operation in format: YYYYMMDDHHMMSS.| `20190301180233` |
| `card_token` |No|String| Card token. The parameter is transmitted if the Partner has the card tokenization option enabled (only used for the "pay" request).| `c0bbb6318f7c442-2b9d787bc9724145-2c0d9250cdd2a1d` |
|`txn_id_own`|No|String| Unique identifier of the transaction in the Partner system: `TransactionID`, sent in the request [[10005]](https://hackmd.io/qSkRHz6gRKmxNrWRwwrjqg). |`5c6e2be`|
| `locale` | Yes | String | Locale (language) of the payment page (the same locale from the request [[10005]](https://hackmd.io/qSkRHz6gRKmxNrWRwwrjqg)). | `uk` |
| `sign` |No|String| The signature is formed using a private key from data strings [concatenation](https://en.wikipedia.org/wiki/Concatenation): </br> `txn_id`+`uuid`+`txn_date`+`sum`. </br> See the signature generation algorithm in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)". |`uDzPcuDjEFlC2FG-2Mjr566GKGIArfK-kcIA3LYTcXmavB3-9QBGmlVyU2yXG64-TM4qDq2kMBxXOQR-ueBMDcYgYkycyTd-Y8Q%3D%3D`|

:::success
<details>
<summary>Example of string formation for "sign" signature </summary>
<br>
Request data:

~~~md
txn_id=321456
uuid=f3cd72b6-e1ea-406f-9b44-a9b93b401b7f
txn_date=20190301180233
sum=100
~~~
Signature string:
~~~md
321456f3cd72b6-e1ea-406f-9b44-a9b93b401b7f20190301_180233100
~~~
</details>
:::

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

~~~md
https://partner.host/protocol?command=pay&txn_id=321456&uuid=f3cd72b6-e1ea-406f-9b44-a9b93b401b7f&account=380638754213&sum=100&pay_type=1&txn_date=20190301180233&locale=uk&sign=uDzPcuDjEFlC2FG2Mjr566GKGIArfKkcIA3LYTcXmavB39QBGmlVyU2yXG64TM4qDq2kMBxXOQRueBMDcYgYkycyTdY8Q%3D%3D
~~~
</details>
:::

## The "refund" Request

The following parameters are sent in the request:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `command` | Yes | String | Operation status: "refund" - refund done.|`refund` |
| `txn_id` | Yes | String | Unique transaction identifier in the Operator system. | `321455` |
| `sum` | Yes | Integer| Payment sum in kopecks. |1UAH=>`100`|
| `operation_id` | Yes | String | Unique operation identifier in the Operator system. | `11` |
| `partner_txn_id` | Yes | String | Unique transaction identifier in the Partner system. | `321455` |
| `partner_terminal_id` | Yes | String | Unique terminal identifier in the Partner system. | `1` |
| `txn_date` |Yes|String| Date and time of operation in format: YYYYMMDDHHMMSS.| `20190301180233` |
| `sign` |No|String| The signature is formed using a private key from data strings [concatenation](https://en.wikipedia.org/wiki/Concatenation): </br> `sum`+`txn_id`+`partner_txn_id`+ `partner_terminal_id`. </br> See the signature generation algorithm in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)". |`uDzPcuDjEFlC2FG-2Mjr566GKGIArfK-kcIA3LYTcXmavB3-9QBGmlVyU2yXG64-TM4qDq2kMBxXOQR-ueBMDcYgYkycyTd-Y8Q%3D%3D`|

## Response to the "pay/error/refund" Request

To the "pay/error/refund" 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 "pay/error" 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` |
| `txn_date` |Yes|String| Date and time of operation in the Partner system. The format is: YYYYMMDDHHMMSS.| `20190301180233` |

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

~~~md
{
"txn_id": "321456",
"result": "10",
"message": "Done",
"txn_date": "20190301180833"
}
~~~
</details>
:::

## Get Operation Status

To get the current operation status at any time, the next request can be sent: [[20003] "Get Operation Status"](https://hackmd.io/_eAjmoG-QPWoWWmsLOGf1g).

## Reference Materials

General parameters of the XPAY system are given in the ["Reference Materials"](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg) section:  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>