[УКР](https://hackmd.io/8DmAChsGRcOkUdZ1KzMy_g) | ENG
:arrow_left: [Guide](https://hackmd.io/pa6TRNZTTa67jO_qYDuRBQ)

# [40002] Get List of Payment Instruments

## Usage

Every authorized user can get a list of payment instruments. Payment instrument has an unique identifier (token), which is transmitted in the "cc_uuid" field (see details in the response). Using the service of getting balance and payment execution is performed with the transfer of payment instrument token.

See the interaction scheme in the section "[General Interaction Scheme](https://hackmd.io/mt4nWXeXTg-4vPFAaqCQ9g)".

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

~~~
{
"UserID": "",
"Phone": "",
"Email": "",
"DeviceID": "",
"Transaction": {
"TransactionID": "",
"TerminalID": "",
"DateTime": ""
}
}
~~~
</details>
:::

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
|`UserID`|No |String|Unique client identifier in the Partner system.|`Uwuh0B5GQVuokYSL`|
| `Phone` | Yes | String | Client phone number in the format "380xxxxxxxxxxxx". |`380679335544`|
| `Email` | No | String | Client email. |`[e-mail]`|
|`DeviceID`|Yes |String|Unique identifier of the client device.|`0Ht9z0yh5aDNr5-js1zGFz5QTmIE=`|
|`Transaction`|Yes|Structure|Structure transmits transaction data. See section "[Transaction Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#2-Data)".|See example below.|

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

~~~md
{
"Partner": {
"PartnerToken": "3b4e5666-b585-491a-af31-516e47b25041",
"OperationType": 40002
},
"Data": "{\"Email\": \"[e-mail]\", \"UserID\": \"Uwuh0B5GQVuokYSL\", \"DeviceID\": \"0Ht9z0yh5aDNr5js1zGFz5QTmIE=\", \"Transaction\": {\"DateTime\": \"2022-04-21 02:46:33\", \"TerminalID\": \"1\", \"TransactionID\": \"JXECMxR4IUCqtsqr5KBkABrKC0M=\"}}",
"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)"*.

### Data Structure

Successful response to the request [40002] contains the array of `CardsList` structures, in which unencrypted or encrypted data of payment instruments is transmitted. The parameters of the structure are optional and are configured individually depending on the Partner's needs.
Main parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
|`name`|No|String|Name of the payment instrument (PI). |`MonoBan`|
|`balance`|No|Integer|Balance of PI (relevant for wallets). |1UAH=>`100`|
|`cc_uuid`|No|String|UUID (unique identifier) of PI. |`ead5ea7a-f19f-44ec-8742-3621b4bfdc18`|
|`mask_pan`|No|String|PI ID: </br> - for wallets - wallet ID; </br> - for cards - masked PAN. |`537541******2121`|
|`pi_type_id`|No|Integer|PI type: </br> `1`- wallet; </br> `2` - card. |`1`|
|`bank_name`|No|String|Bank name (for cards). |`UNIVERSAL BANK`|
|`channel_name`|No|String|Payment system name (for cards). |`MasterCard (IPM)`|

### Response Examples

:::success
<details>
<summary>List of payment instruments in unencrypted form</summary>
<br>

~~~md
{
"Code": 200,
"Message": "done",
"Data": {
"DecodedData": "{\"CardsList\":[{\"name\":\"MonoBan\",\"balance\":0,\"cc_uuid\":\"ead5ea7a-f19f-44ec-8742- 3621b4bfdc18\",\"mask_pan\":\"537541******2121\",\"pi_type_id\":2,\"bank_name\":\"UNIVERSAL BANK\",\"channel_name\": \"MasterCard (IPM)\"},{\"name\":\"\",\"balance\":456782,\"cc_uuid\":\"142b675c-690e-4063-ab34-895d4be043b0\", \"mask_pan\":\"UAH540110155\",\"pi_type_id\":1,\"bank_name\":\"Bank\",\"channel_name\":\"Card\"}]}",
"OperationID": 11,
"OperationStatus": 10
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

:::success
<details>
<summary>Operation Failed</summary>
<br>

~~~md
{
"Code": 200,
"Message": "fail",
"Data": {
"OperationID": 111,
"OperationStatus": 21,
"Reason": 3
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

## 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/pa6TRNZTTa67jO_qYDuRBQ)
:arrow_left: [General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)

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

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