---
# System prepended metadata

title: '[10101] Card-Card'

---

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

# [10101] Card-Card

*What is "Server-Server card payment" and how the sender is authenticated, see in the section "[Server-Server Card Payment](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg)".*


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

~~~
{
    "Sum": ,
    "Commission": [
        {
        "sm": , 
        "to": , 
        "prc": , 
        "from": ,
        "min_sm": ,
        "max_sm": 
        }
    ],
    "Action": "Prepare"/"Pay",
    "GoogleToken/AppleToken": "",
    "Currency": "",
    "Exchange": "",
    "Purpose": "",
    "SenderCard": {
        "PAN": "",
        "ExpMon": "",
        "ExpYear": "",
        "CVV": "",
        "Cryptogram": "",
        "Gateway": "",
        "eciIndicator": "",
        "IBAN": ""
    },
    "RecipientCard": {
        "PAN": ""
    },
    "SenderPerson": {
        "FirstName": "",
        "LastName": "",
        "MiddleName": "",  
        "Phone": "",
        "Email": "",
        "Address": "",
        "City": "",
        "CountryCode": "",
        "PostCode": "",
        "State": ""
    },
    "RecipientPerson": {
        "FirstName": "",
        "LastName": "",
        "MiddleName": "",
        "Address": "",
        "City": "",
        "CountryCode": "",
        "PostCode": "",
        "State": ""
    },
    "CallbackURL": "",
    "Transaction": {
        "TransactionID": "",
        "TerminalID": "",
        "DateTime": ""
    },
    "BrowserData": {
        "device": {
            "channel": ""
        },
        "browserIP": "",
        "browserTZ": ,
        "browserLanguage": "",
        "browserUserAgent": "",
        "browserColorDepth": ,
        "browserJavaEnabled": ,
        "browserScreenWidth": ,
        "browserScreenHeight": ,
        "fraudhuntFingerprint": ""
    }
}
~~~
</details>
:::


|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `Sum` | Yes |Integer | Operation sum in kopecks. |1UAH=>`100`|
|`Commission`^1^|No|Array| Array of structures transmits the rules for calculating the commission added to the transaction sum.|See below.|
|`Action`|No|String|Request type: `Prepare` - commission calculation, or `Pay` - payment (default value). |`Prepare` or `Pay`|
|`GoogleToken` / `AppleToken`|No|String|Sender card token, transmitted when paying with the "Google/Apple Pay" method. |`24iOiJFQ3YyI-UwMDNk9In0...`|
| `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`|
| `Purpose` | No | String | Payment purpose. |`Payment Order No.333` |
|`SenderCard`^2^|Yes|Structure|Structure transmits sender's bank card data.|See example below.|
|`RecipientCard`^3^|Yes|Structure|Structure transmits recipient's bank card data.|See example below.|
|`SenderPerson`^4^|Yes - paying in a currency different from UAH.|Structure|Structure transmits sender's personal  data.|See example below.|
|`RecipientPerson`^5^|Yes - paying in a currency different from UAH.|Structure|Structure transmits recipient's personal data.|See example below.|
| `CallbackURL` | No | String | URL to which the client will be redirected after checkout. See section ["Server-Server Card Payment"](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg). |`https://partner.host/ resul_page`|
|`BrowserData`|No|Structure|Structure transmits browser data for *3DSecure 2.0*. See section ["BrowserData structure"](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg#%E2%80%9CBrowserData%E2%80%9D-structure).|See example in section ["BrowserData structure"](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg#%E2%80%9CBrowserData%E2%80%9D-structure).|
|`Transaction`|Yes|Structure|Structure transmits transaction data. See section "[Transaction Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#2-Data)".|See example below.|


^1^ **"Commission"** Array Parameters:

|Parameter|Required|Type|Description|Example| 
|:----:|:----:|:----:|----|:----:|
|`sm`|Yes/No `sm`or`prc`|Integer|Fixed commission sum (in kopecks). |`500`|
|`from`|Yes|Integer| Operation sum "from" inclusively is the lower limit of the range (in kopecks).|`0`|
|`to`|Yes|Integer| Operation sum "to" inclusive is the upper limit of the range (in kopecks).|`99999`|
|`min_sm`|No|Integer|Minimum commission sum (in kopecks). If the settlement commission is smaller, the commission will be equal to `min_sm`. |`200`|
|`max_sm`|No|Integer|Maximum commission sum (in kopecks). If the settlement commission is higher, the commission will be equal to `max_sm`. |`500`|
|`prc`|Yes/No `sm`or`prc`|Integer|Percentage of the transaction sum (value `1`=1%). It is allowed to send both parameters: `sm` and `prc`. In this case, the commission sum is equal to: `Sum*prc/100+sm`, where `Sum` is the transaction sum. |`1`|


^2^ **"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`|
|`Cryptogram`|No|String|Cryptogram of the decrypted "Google/Apple Pay" token. A cryptogram is a dynamic one-time code of each transaction accompanying the token. |`AFYjls2Of..XFAoABFA==`|
|`Gateway`|Yes, if parameter `Cryptogram` is transmitted.|String|Tokenization gateway for "Google/Apple Pay". Parameter is transmitted only when the card data was got as a result of data decryption.|`gpay` or `applepay`|
|`eciIndicator`|Yes, if parameter `Cryptogram` is transmitted.|String| [ECI indicator](https://developer.visa.com/request_response_codes#moto_eci_ind_codes), the value from the decrypted "Google/Apple Pay" cryptogram. |`7`|
| `IBAN` | No </br> (agreed at integration stage) | String | Sender IBAN (International Bank Account Number). | `UA4830529900000-26008031203677` |


^3^ **"RecipientCard"** Structure Parameters:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `PAN` | Yes | String[16] | Recipient card PAN (bank card number). | `8888888888888888` |


^4^ **"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`|
| `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)`|


^5^ **"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`|
| `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
*Parameters are transmitted only using a sender/recipient card not issued by the Bank of Ukraine.
:::


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

~~~md
{
  "Sum": 45500,
  "Action": "Pay",
  "Currency": "UAH",
  "GoogleToken/AppleToken": "24iOiJFQ3YyI-UwMDNk9In0...",
  "Exchange": "UAH",
  "SenderCard": {
    "CVV": "***",
    "PAN": "535124******0453",
    "ExpMon": "12",
    "ExpYear": "24"
  },
  "Transaction": {
    "TerminalID": "1",
    "TransactionID": "8fd04e6e-c7c1-4bb6-8ee0-e67116062cf5"
  },
  "SenderPerson": {
    "LastName": "",
    "FirstName": "",
    "MiddleName": ""
  },
  "RecipientCard": {
    "PAN": "537541******5416"
  },
  "RecipientPerson": {
    "LastName": "",
    "FirstName": "",
    "MiddleName": ""
  }
}
~~~
</details>
:::


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

~~~md
{
  "Partner": {
    "PartnerToken": "72a8ddb8-9145-4a41-af1a-8c48ecaa4be1",
    "OperationType": 10101,
    "Locale": "uk"
  },
  "Data": "{\"Sum\":50000,\"Action\":\"Pay\",\"SenderCard\":{\"PAN\":\"535124******5859\",\"ExpMon\":\"**\",\"ExpYear\":\"**\",\"CVV\":\"***\"},\"RecipientCard\":{\"PAN\":\"402961******1409\"},\"SenderPerson\":{\"LastName\":\"\",\"FirstName\":\"\",\"MiddleName\":\"\"},\"RecipientPerson\":{\"LastName\":\"\",\"FirstName\":\"\",\"MiddleName\":\"\"},\"Currency\":\"UAH\",\"Exchange\":\"UAH\",\"Transaction\":{\"TransactionID\":\"57a250f3-2336-4531-9cf9-3d2ee0c468f2\",\"TerminalID\":\"1\"}}",
  "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.                      | `25000` |
|   `Fee`    |   Yes    | Integer | Sum of fee (commission) in kopecks.                         | `1000`  |
| `TotalSum` |   Yes    | Integer | Total operation sum in kopecks, including commission. | `26000` |


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

~~~md
{
  "Code": 102,
  "Message": "done",
  "Data": {
    "Fee": 1000,
    "OperationID": 82769659,
    "OperationStatus": 7,
    "Sum": 25000,
    "TotalSum": 26000
  },
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::


### Parameter "Action":"Pay"

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


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

:::success
<details>
<summary>Request successfully accepted and needs "3DS" verification</summary>
<br>

~~~md
{
  "Code": 102,
  "Message": "need3ds",
  "Data": {
    "OperationID": 111,
    "3dsHtml": "<html page in base64 encoding>",
    "OperationStatus": 2
  },
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::


:::success
<details>
<summary>Request successfully accepted and needs "OTP" verification</summary>
<br>

~~~md
{
  "Code": 102,
  "Message": "needOTP",
  "Data": {
    "OperationID": 111,
    "otpJson": "<JSON structure as string>",
    "OperationStatus": 3
  },
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::


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


## Related Requests

[[10102/101023/101025] Card-Wallet](https://hackmd.io/MUZzd3mTRQeQfBsE-emVVQ)
[[10103] Card-IBAN of Individual](https://hackmd.io/9c9kaHeMTH-LiGf_mVWwpg)
[[101031] Card-IBAN of Legal Entity](https://hackmd.io/XQDv9qmoRiqFzfzcD0H1uA)
[[10150/10051] Card-Phone-Card](https://hackmd.io/ES9hW5BlS6CozQAmULgnRw) 


**Token Payment**
[[104021] Card Payment by Token](https://hackmd.io/I4FJ0d0eStuvfqG2YmS8IQ)
[[1040217] Bulk Card Payment by Token](https://hackmd.io/6h9zyYaBTwOLzzP8XJDrfg)
[[104121] Auto Debit by Token. MO/TO Operations](https://hackmd.io/X4ImobdtSJ-Hy1qM-p7PWA)


**Get Card Data** 
[[20400/20410] Get Card Data by Phone Number](https://hackmd.io/Xd9OZWXARcSZRTCsu-1jrw)
[[20404] Get Card Data by Token](https://hackmd.io/PSdh1ldNSmmJMR4OIhM_-Q)


**Get Transaction Data**
[[20003] Get Operation Status](https://hackmd.io/_eAjmoG-QPWoWWmsLOGf1g)
[[20009] Get Limit for Operation [10101]](https://hackmd.io/rQ7epWnbQmG9kM0rFjUfhA)
[[20110] Get Card Data](https://hackmd.io/WruG7PGDRsuF0gL0Wl21bA)


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

