[УКР](https://hackmd.io/QF_yny3cRpCuQdUZq7dpyA) | ENG
:arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw)
# [10303] Wallet-IBAN
*What is "XPAY Wallet" see in the section ["XPAY Wallet"](https://hackmd.io/bbv1AdS0SwiJeWqW1i1tCA).*
## Usage
Request [10303] is used to transfer funds from the Partner's wallet to the specified details (IBAN).
## 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
Data structure for this operation is formed from the following parameters:
:::info
<details>
<summary>Data structure formation (examples are below)</summary>
<br>
~~~
{
"Phone": "",
"Email": "",
"Sum": ,
"Currency": "",
"Exchange": "",
"Purpose": "",
"Sender": {
"MFO": "",
"Name": "",
"EDRPOU": "",
"Account": "",
"CountryResidence": "",
"ActualCountry": "",
"Country": "",
"City": "",
"Street": "",
"Building": ""
},
"Recipient": {
"Name": "",
"MFO": "",
"EDRPOU": "",
"Account": ""
},
"SenderPerson": {
"FirstName": "",
"LastName": "",
"MiddleName": "",
"IPN": "",
"Birthday": "",
"Birthplace": "",
"Phone": "",
"Email": "",
"Address": "",
"City": "",
"CountryCode": "",
"PostCode": "",
"State": ""
},
"RecipientPerson": {
"FirstName": "",
"LastName": "",
"MiddleName": "",
"IPN": "",
"Birthday": "",
"Birthplace": "",
"Address": "",
"City": "",
"CountryCode": "",
"PostCode": "",
"State": ""
},
"MIDs": [
{
"MID": ,
"Sum": ,
"PaymentInfo": [
{
"Caption": "",
"Value": ""
}
]
}
],
"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`|
| `Sum` | Yes |Integer | Operation sum in kopecks. |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) ("UAH", "GBP", "USD", etc.). |`UAH`|
| `Exchange` | Yes - paying in a currency different from UAH. | String | Currency *credit* code is an abbreviated currency designation described in the standard [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Non_ISO_4217_currencies) ("UAH", "GBP", "USD", etc). |`UAH`|
|`Sender`^1^|Yes*|Structure|Structure transmits actual sender's bank account details.|See example below.|
|`Recipient`^2^|Yes*|Structure|Structure transmits recipient's (legal entity) bank account details. |See example below.|
|`SenderPerson`^3^|Yes*|Structure|Structure transmits sender's personal data.|See example below.|
|`RecipientPerson`^4^|Yes*|Structure|Structure transmits recipient's personal data.|See example below.|
| `MIDs`^5^ | No | Array | Array is transmited to make a payment from the merchant's wallet to the service provider, on condition that Partner can use balances of the associated merchants. | See example below.|
| `Purpose` | No | String | Payment purpose. | `Transfer No.1178341032 from KATERYNA KHOMCHENKO` |
|`Transaction`|Yes|Structure|Structure transmits the transaction data. See section "[Transaction Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#2-Data)".|See example below.|
**Parameters are conditionally mandatory depending on the transfer type (determined at the integration stage).*
^1^ **"Sender"** Structure Parameters:
|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Name` |No |String | Sender name.| `Altera LLC` |
| `MFO`| No | String | Sender "[Bank Sort Code](https://en.wikipedia.org/wiki/Sort_code). | `305299` |
| `EDRPOU` | No | String | Sender ["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. |`3505506226`|
| `Account` | Yes | String | Sender сurrent account or IBAN (International Bank Account Number). | `UA4830529900000-26008031203677` |
| `CountryResidence` | No | String | Sender country code of residence, according to the directory: ["ISO 3 digit"](https://docs.dnb.com/partner/en-US/iso_country_codes). |`470`|
| `Country` | No | String | Sender country code. |`470`|
| `ActualCountry` | No | String | Sender actual country code. |`470`|
| `City` | No | String | Sender city. |`City`|
| `Street` | No | String | Sender street. |`Street`|
| `Building` | No | String | Sender building number. |`1`|
^2^ **"Recipient"** Structure Parameters:
|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Name` |No |String | Recipient name.| `Kvadrat LLC` |
| `MFO`| No | String | Recipient "[Bank Sort Code](https://en.wikipedia.org/wiki/Sort_code). | `305299` |
| `EDRPOU` | No | 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. |`34190717`|
| `Account` | Yes | String | Recipient сurrent account or IBAN (International Bank Account Number). | `UA4830529900000-26008031203677` |
^3^ **"SenderPerson"** Structure Parameters:
|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `FirstName` | No | String | Sender name. |`Oleg`|
| `MiddleName` | No | String | Sender middle name. |`Mykhaylovich`|
| `LastName` | No | String | Sender last name. |`Podilskyi`|
| `IPN` | No* </br> `IPN` or </br>`Birthday`+`Birthplace` | String | Sender individual tax number. |`111111111111`|
| `Birthday` | No* </br> `IPN` or </br>`Birthday`+`Birthplace` | String | Sender birthday. |`2000-06-14`|
| `Birthplace` | No* </br> `IPN` or </br>`Birthday`+`Birthplace` | String | Sender birthplace. |`Vinnytsia, Ukraine`|
| `Phone` | No | String | Sender phone number in the format: "380xxxxxxxxxxxx". |`380679335544`|
| `Email` | No | String | Sender email. |`index@gmail.com`|
| `Address`** | No | String | Sender billing address. |`456 Main Street`|
| `City`** | No | String | Sender city. |`San Diego`|
| `CountryCode`** | No | String | Sender country code (ISO CODES), according to table "[Country Codes](https://countrycode.org/)". |`US`|
| `PostCode`** | No | String | Sender index. |`92126`|
| `State`** | No | String | Sender state. |`California (CA)`|
^4^ **"RecipientPerson"** Structure Parameters:
|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `FirstName` | No | String | Recipient name. |`Andrew`|
| `MiddleName` | No | String | Recipient middle name. |`Valeriiovich`|
| `LastName` | No | String | Recipient last name. |`Mazur`|
| `IPN` | No* </br> `IPN` or </br>`Birthday`+`Birthplace` | String | Recipient individual tax number. |`111111111111`|
| `Birthday` | No* </br> `IPN` or </br>`Birthday`+`Birthplace` | String | Recipient birthday. |`2000-06-14`|
| `Birthplace` | No* </br> `IPN` or </br>`Birthday`+`Birthplace` | String | Recipient birthplace. |`Vinnytsia, Ukraine`|
| `Address`** | No | String | Recipient billing address. |`pl. Bankowy 3/5`|
| `City`** | No | String | Recipient city. |`Warszawa`|
| `CountryCode`** | No | String | Recipient country code (ISO CODES), according to table "[Country Codes](https://countrycode.org/)". |`PL`|
| `PostCode`** | No | String | Recipient index. |`00-950`|
| `State`** | No | String | Recipient state. |-|
:::warning
*`Birthday` and `Birthplace` parameters are transmitted in the absence of the sender/recipient individual tax number.
** Parameters are transmitted only using a sender/recipient card not issued by the Bank of Ukraine.
:::
^5^ **"MIDs"** Array Parameters:
|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `MID` |Yes| Integer | Merchant ID in the Operator system, from which wallet funds are debited. |`111`|
| `Sum` | Yes |Integer | Payment sum in kopecks. |1UAH=>`100`|
| `PaymentInfo`^6^ | No | Array | Parameter is used to display additional payment details on the payment page. | See example below.|
^6^ **"PaymentInfo"** Array Parameters:
|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Caption` |Yes| String | Description of additional information. |`Purpose`|
| `Value` |Yes| String | Additional Information. |`Contract Repayment No. 3642989012-5 from 04/03/2021 Pupkina Valeriya Serhiivna`|
:::success
<details>
<summary>Example of "Data" structure of the request [10303]</summary>
<br>
~~~md
{
"Phone": "380637355533",
"Sum": 500200,
"Currency": "UAH",
"Exchange": "UAH",
"Purpose": "Transfer No. 1178341032",
"Sender": {
"MFO": "305299",
"Name": "Altera LLC",
"EDRPOU": "",
"Account": "UA483052990000026008031203677",
"CountryResidence": "470",
"ActualCountry": "470",
"Country": "470",
"City": "City",
"Street": "Street",
"Building": "1"
},
"Recipient": {
"MFO": "305299",
"EDRPOU": "3505506226",
"Account": "UA483052990000026008031203677"
},
"RecipientPerson": {
"FirstName": "Andriy",
"LastName": "Mazur",
"IPN": "856431209583"
},
"MIDs": [
{
"MID": 111,
"Sum": 100,
"PaymentInfo": [
{
"Caption": "Purpose",
"Value": "Contract Repayment No. 3642989012-5 from 04/03/2021 Pupkina Valeriya Serhiivna"
}
]
},
{
"MID": 112,
"Sum": 200,
"PaymentInfo": [
{
"Caption": "Purpose",
"Value": "Contract Repayment No. 3642989012-5 from 04/03/2021 Pupkina Valeriya Serhiivna"
}
]
}
],
"Transaction": {
"DateTime": "20220712 22:39:02",
"TerminalID": "1",
"TransactionID": "1178341032"
}
}
~~~
</details>
:::
## Response
*See the general information on the response structure formation in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)"*.
### Response Examples
:::success
<details>
<summary>Operation Successfully Completed</summary>
<br>
~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"OperationID": 555,
"OperationStatus": 10
},
"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>
:::
## Test Data
:::info
To test this request, use **Test Partner** parameters. See section: ["Test Partner Settings"](https://hackmd.io/1Ftkd9PVSvGBc9JV8f9b9A).
<details>
<summary>Test request</summary>
<br>
~~~md
{
"Partner": {
"PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
"OperationType": 10303,
"Locale": "uk"
},
"Data": "{\"Phone\": \"380277777777\", \"Email\": \"testmail@mail.com\", \"Sum\": 5600, \"Currency\": \" UAH\", \"Exchange\": \"UAH\", \"Purpose\": \"\\u041f\\u0435\\u0440\\u0435\\u043a\\u0430\\u0437 \\u043a\\ u043e\\u0448\\u0442i\\u0432 \\u21161178341032 \\u0432\\u0456\\u0434 KATERYNA KHOMCHENKO\", \"Sender\": {\"MFO\": \"305299\", \"Name\" ": \"Square LLC\", \"EDRPOU\": \"3505506226\", \"Account\": \"UA483052990000026008031203677\", \"CountryResidence\": \"470\", \"Country\" : \"470\", \"City\": \"New York\", \"Street\": \"5420 Street\", \"Building\": \"21\"}, \"Recipient\ ": {\"Name\": \"Circle LLC\", \"MFO\": \"305311\", \"EDRPOU\": \"3505506337\", \"Account\": \"UA483052990000026008031203677\" "}, \"SenderPerson\": {\"FirstName\": \"Test\", \"LastName\": \"Testovych\", \"MiddleName\": \"Testyansky\", \"IPN\ ": \"111111111111\", \"Birthday\": \"2000-06-14\", \"Birthplace\": \"Vinnytsia, Ukraine\", \"Address\": \"380288888888\", \"City\": \"Los Angeles\", \"CountryCode\": \"US\", \"PostCode\": \"92126\", \"State\": \"CA\"}, \"RecipientPerson\": {\"FirstName\": \"Anton\", \"LastName\": \"Pavlovych\", \"MiddleName\": \"Shpak\", \"IPN\": \ "111111111222\", \"Birthday\": \"2000-06-14\", \"Birthplace\": \"Vinnytsia, Ukraine\", \"Address\": \"pl. Bankowy 3/5\", \"City\": \"Warszawa\", \"CountryCode\": \"PL\", \"PostCode\": \"00-950\", \"State\" : \"\"}, \"MIDs\": [{\"MID\": 111, \"Sum\": 5600, \"PaymentInfo\": [{\"Caption\": \"\\u041f \\u0440\\u0438\\u0437\\u043d\\u0430\\u0447\\u0435\\u043d\\u043d\\u044f\", \"Value\": \"\\u041f\\u043e\\u0433 \\u0430\\u0448\\u0435\\u043d\\u043d\\u044f \\u0437\\u0430 \\u043a\\u043e\\u043d\\u0442\\u0440\\u0430\\u043a\\u0442\\ u043e\\u043c \\u21163642989012-5 \\u0432\\u0456\\u0434 04/03/2021 \\u041f\\u0443\\u043f\\u043a\\u0456\\u043d\\u0430 \\u0412\\u0430\\ u043b\\u0435\\u0440\\u0456\\u044f \\u0421\\u0435\\u0440\\u0433\\u0456\\u0457\\u0432\\u043d\\u0430\"}]}], \"Transaction \": {\"TransactionID\": \"1ezQdLeqEQbl5unGqwo6MA\", \"TerminalID\": \"1\", \"DateTime\": \"20240221 15:37:01\"}}",
"KeyAES": "",
"Sign": ""
}
~~~
</details>
<details>
<summary>Expected response</summary>
<br>
~~~md
{
"Code": 102,
"Message": "In progress",
"Data": {
"OperationID": 9620165,
"OperationStatus": 5
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::
## Related Requests
[[10301/10311/103013] 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)
[[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)
[[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.
: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>
Sign in with Wallet
Connect another wallet