---
# System prepended metadata

title: '[10405] Token-Phone'

---

[УКР](https://hackmd.io/gsTvGhrDTjqlNE_ZZa22vA) | ENG
![](https://i.imgur.com/ULmPUgP.jpg)
:arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw)

# [10405] Token-Phone

*What is "Token Payment" and how the cards are tokenized, see in the section ["Token Payment"](https://hackmd.io/hELnx1lqQwS9RiactYbLEA).*


## Usage

Request [10405] is used to top up a mobile phone by the card token.


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

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

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

~~~
{
    "Phone": "",
    "Email": "",
    "ClientToken": "",
    "Action": "Prepare” / “Pay",
    "Sum": ,
    "Recipient": "",
    "Transaction": {
        "TransactionID": "",
        "TerminalID": "",
        "DateTime": ""
    }
}
~~~
</details>
:::


|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Phone` | Yes | String | Sender phone number in format: "380xxxxxxxxxxxx". |`380679335544`|
| `Email` | No | String | Sender email.|`index@gmail.com`|
|`ClientToken`|Yes|String|Sender card token.|`d1d2a97aac30eefd26959842-55d2bf3b236a2f84b4e8e2a1-d12c291f4e669`|
|`Action`|No|String|Request type: `Prepare` - commission calculation, or `Pay` - payment (default value). |`Prepare` or `Pay`|
| `Sum` | Yes |Integer| Operation sum in kopecks. |1UAH=>`100`|
|`Recipient`|Yes|String|Phone number to be topped up in format: "380xxxxxxxxx". |`380675670090`|
|`Transaction`|Yes|Structure|Structure transmits the transaction data. See section "[Transaction Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#2-Data)".|See example below.|


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

~~~md
{
  "Sum": 25000,
  "Phone": "380934728867",
  "Action": "Pay",
  "ClientToken": "d1d2a97aac30eefd2d69598425d2bf3b2316a2f84b48e2a1d1b2c291f4e669",
  "Recipient": "380733180234"
  },
  "Transaction": {
    "DateTime": "2022-07-13 09:53:39",
    "TerminalID": "88b326d1-dc1f-48bf-b36a-dc9768e96117",
    "TransactionID": "cc50127f-1405-4160-afa6-36437c07c8dd"
  }
}
~~~
</details>
:::

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

~~~md
{
  "Partner": {
    "PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
    "OperationType": 10405
  },
  "Data": "{\"Phone\":\"380934728867\",\"Action\":\"Pay\",\"ClientToken\":\"d1d2a97aac30eefd2d69598425d2bf3b2316a2f84b48e2a1d1b2c291f4e669\",\"Sum\":25000,\"Recipient\":\"380733180234\",\"Transaction\":{\"TransactionID\":\"cc50127f-1405-4160-afa6-36437c07c8dd\",\"TerminalID\":\"88b326d1-dc1f-48bf-b36a-dc9768e96117\",\"DateTime\":\"2022-07-13 09:53:39\"}}",
  "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)"*.


### Parameter "Action":"Prepare"

When the request value `"Action":"Prepare"` is sent, the commission calculation data is transmitted in the "Data" response structure:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
|`Sum`|Yes|Integer|Sum of the operation in kopecks. |`500`|
|`Fee`|Yes|Integer|Sum of commission in kopecks.|`50`|
|`TotalSum`|Yes|Integer|Total operation sum in kopecks, including commission.|`550`| 


:::success
<details>
<summary>Response example for request value "Action":"Prepare"</summary>
<br>

~~~md
{
   "Code": 102,
   "Message": "done",
   "Data": {
     "Sum": 500,
     "Fee": 50,
     "TotalSum": 550,
     "OperationStatus": 7
   },
   "KeyAES": "",
   "Sign": ""
}
~~~
</details>
:::


### Parameter "Action":"Pay"

:::info
For payment, you need to repeat the request [10405] with the same data, but specify the value `Pay` in the parameter `Action`. 
:::

Successful response to the request contains the structure `Receipt`, that transmits the top-up data:

| Parameter | Obligation | Type | Description | Example
|:----:|:----:|:----:|----|:----:|
| `payment_purpose` |Yes| String | Payment purpose. |`Payment for mobile services`|
| `recipient_account` |Yes| String | Recipient IBAN (international bank account number). | `UA1730529900000-26207893720887`|
| `recipient_bank` |Yes| String | Recipient bank name. | `PJSC ALFA-BANK in KYIV` |
| `recipient_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. | `21673832` |
| `recipient_mfo` |Yes| String | Recipient "[Bank Sort Code](https://en.wikipedia.org/wiki/Sort_code).|`300346`|
| `recipient_name` |Yes| String | Recipient name or full name. |`PJSC Kyivstar`|


:::warning
`Receipt` data is not sent when re-requesting or receiving operation status.
:::


#### Response Examples for Request Value "Action":"Pay"

:::success
<details>
<summary>Operation Successfully Completed</summary>
<br>

~~~md
{
   "Code": 200,
   "Message": "Ok",
   "Data": {
     "OperationDate": "2020-12-07T17:03:06.661937+02:00",
     "OperationID": 29561653,
     "OperationStatus": 10,
     "Receipt": {
       "payment_purpose": "Payment for mobile services",
       "recipient_account": "UA403003460000026008010065101",
       "recipient_bank": "PJSC ALFA-BANK in KYIV",
       "recipient_edrpou": "21673832",
       "recipient_mfo": "300346",
       "recipient_name": "PJSC_Kyivstar"
     }
   },
   "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>
:::


## Related Requests

[[10301/10311/10313] Wallet-Card](https://hackmd.io/SvLoAv49QWOIsdPhCWFezA)
[[10204/10214] Wallet-Card by Token](https://hackmd.io/-8jNNh0SQeKZ-6tbwp15OQ)
[[10202] Wallet-Wallet](https://hackmd.io/dOi__3dxSYSi_3EvZh2a5Q)
[[10303] Wallet-IBAN](https://hackmd.io/7kfzI0OAQB6Nt8ZN38UxSg)
[[10304] Wallet-UUID](https://hackmd.io/-U0QJEY_TASmrNQGwGepcA)
[[10400] Packet Payment Wallet-Card by Token](https://hackmd.io/BHS4jBINQ-u8SQxX3XvR6Q)
[[10401] Packet Payment Wallet-Card by Card Number](https://hackmd.io/v65TGa0uQPGCrKXQhvHuZg)


**Phone Top-Up**
[[10205] Wallet-Phone](https://hackmd.io/eyewES-3TCGr99R8shURgQ)
[[10305] Card-Phone](https://hackmd.io/RFSxYF85Q0WqOd8I6Xenjg)


**Get Transaction Data**
[[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.


![](https://i.imgur.com/17gAyWb.png)
: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: +38 093 891 92 00
Email: info@xpay.com.ua
Telegram: @xpaysupportbot
</details>




















