[УКР](https://hackmd.io/XGJE11L3T_KwUtIR1Qlf_Q) | ENG ![](https://i.imgur.com/ULmPUgP.jpg) :arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw) # [10305] Card-Phone *What is "XPAY Wallet", see in the section ["XPAY Wallet"](https://hackmd.io/bbv1AdS0SwiJeWqW1i1tCA).* ## Usage Request [10305] is used to top up a mobile phone by the card. ## 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> ~~~ { "SenderCard": { "PAN": "", "ExpMon": "", "ExpYear": "", "CVV": "" }, "Phone": "", "Email": "", "Action": "Prepare” / “Pay", "Sum": , "Recipient": "", "Transaction": { "TransactionID": "", "TerminalID": "", "DateTime": "" } } ~~~ </details> ::: |Parameter|Required|Type|Description|Example| |:----:|:----:|:----:|----|:----:| |`SenderCard`^1^|Yes|Structure|Structure transmits the sender's bank card data.|See example below.| | `Phone` | Yes | String | Sender phone number in format: "380xxxxxxxxxxxx". |`380679335544`| | `Email` | No | String | Sender email.|`index@gmail.com`| |`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.| ^1^ **"SenderCard"** Structure Parameters: |Parameter|Required|Type|Description|Example| |:----:|:----:|:----:|----|:----:| | `PAN` | Yes | String[16] | Sender card PAN (bank card number). | `8888888888888888` | |`ExpMon`|Yes|String[2]|Month of card validity. Parameter is aligned to 2 digits by the symbol "0".|`02`| |`ExpYear`|Yes|String[2]|Last 2 digits of the card's expiration year. Parameter is aligned to 2 digits by the symbol "0".|`22`| |`CVV`|Yes|String[3]|CVV card code.|`356`| :::success <details> <summary>Example of "Data" structure</summary> <br> ~~~md { "Sum": 25000, "Phone": "380934728867", "Action": "Pay", "Recipient": "380733180234", "SenderCard": { "CVV": "***", "PAN": "426046******2950", "ExpMon": "08", "ExpYear": "24" }, "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 [10305]</summary> <br> ~~~md { "Partner": { "PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1", "OperationType": 10305 }, "Data": "{\"SenderCard\":{\"PAN\":\"426046******2950\",\"ExpMon\":\"**\",\"ExpYear\":\"**\",\"CVV\":\"***\"},\"Phone\":\"380934728867\",\"Action\":\"Pay\",\"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 [10305] with the same data, but specify the value `Pay` in the parameter `Action`. ::: Successful response to the request contains the parameter`RRN` and the structure `Receipt`: |Parameter|Required|Type|Description|Example| |:----:|:----:|:----:|----|:----:| | `RRN` | Yes | String | Reference Retrieval Number - unique identifier of the bank transaction. |`015014474493`| |`Receipt`^2^|Yes|Structure|The structure that transmits the replenishment data.|See example below.| ^2^ **"Receipt"** Structure Parameters: |Parameter|Required|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, "RRN": "015014474493", "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) [[10405] Token-Phone](https://hackmd.io/hRrNYs3wQYeHChpNSk0AFg) **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>