# Payment App Integration Protocol

### 1. Introduction

This document descripts data exchange protocol between Cashier and WIZARPOS terminal. The Cashier is caller to perform transactions and Terminal will listen to Cashier and execute financial transaction.

### 2. Transaction Flow

![](https://2631785516-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY7FuzH91SaNfvhwFA9Ic%2Fuploads%2FOEuu2rTDOIjwhq3BNLft%2F0.png?alt=media)

1. **Cashier shall send Handshake Request at first to confirm connection is ready.**
2. **After Handshake, Cashier shall perform transaction and send Transaction Request which contains payment data.**
3. **POS execute transaction and response the result.**

### 3. Communication Configuration

| Serial port | Default Baud Rate: 115200 |
| ----------- | ------------------------- |
| TCP server  | Default port：6031         |
|             |                           |

### 4. Data Format

Data package between Cashier and Terminal.

<table data-full-width="true"><thead><tr><th>STX</th><th>VERSION</th><th>CTRL</th><th>LEN</th><th width="133">CONTENT</th><th>ETX</th><th>BCC</th></tr></thead><tbody><tr><td><strong>0x02</strong></td><td><mark style="background-color:blue;"><strong>0x02</strong></mark></td><td><strong>(4 bytes)</strong></td><td><strong>(2 bytes)</strong></td><td><strong>(LEN bytes)</strong></td><td><strong>0x03</strong></td><td><strong>(1 byte)</strong></td></tr></tbody></table>

**STX** indicate start byte of data package.

```
Fixed 0x02
```

**VERSION** indicate protocol version.

**CTRL** indicate control bytes of data package.

```
Byte 1: 	
    0x01 indicate data from Cashier
    0x02 indicate data from POS
    0xF1 indicate Handshake Request
    0xF2 indicate Handshake Response
    0xC1 indicate Cancel Request
    0xC2 indicate Cancel Response
Byte 2: 		
    Reserved. Set to 0x00.
Byte 3-4:	
    Sequence number, request package set to X, response package set to X+1 exp. 
    Request [01] [0F], Response [01] [10]

```

**LEN** indicate length bytes of CONTENT. Hex format.

```
Exp. [01] [0F] means 0x10F (271) bytes.
```

**CONTENT** indicate main content of transaction.

**ETX** indicate end byte, Fixed **0x03**.

**BCC** indicate package check value, from VERSION (contain) to ETX (contain).

```
BCC algorithm:
BCC := [VERSION] xor [CTRL Byte1] xor [CTRL Byte2] xor … xor [ETX]
```

### 5. Handshake Request Content

| CONTENT   |
| --------- |
| (4 bytes) |

**Handshake request content is 4 bytes random value.**

### 6. Handshake Response Content

| CONTENT   |
| --------- |
| (4 bytes) |

**Handshake response content should be same with the request.**

### 7. Transaction Request Content

**Transaction Request is content is json format as below:**

<table data-full-width="true"><thead><tr><th>NAME</th><th>FORMAT</th><th data-type="checkbox">MANDATORY</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td><strong>TransType</strong></td><td>String</td><td>true</td><td><p>Indicate transaction type to be performed.</p><p><a href="#a1.1_transaction_type">See A1.1 Transaction Type</a></p></td></tr><tr><td><strong>TransScheme</strong></td><td>String</td><td>false</td><td><p>Cooperation with TransType，used in specific schemes</p><p><a href="#a1.2_transaction_type">See A1.2 Transaction Scheme</a></p></td></tr><tr><td><strong>CallerName</strong></td><td>String</td><td>false</td><td>Caller name</td></tr><tr><td><strong>TransIndexCode</strong></td><td>String</td><td>false</td><td><p>Indicate Cashier trace number</p><p>Should be unique for every transaction</p></td></tr><tr><td><strong>BusinessNum</strong></td><td>String</td><td>false</td><td>Business registration number</td></tr><tr><td><strong>TerminalNum</strong></td><td>String</td><td>false</td><td>Terminal number</td></tr><tr><td><strong>TransAmount</strong></td><td><p>String</p><p>[Mandatory for payment]</p></td><td>true</td><td><p>Total amount including OtherAmount and TipAmount</p><p>“112233” means 1122.33(USD) or 112.233(JOD) depending on CurrencyCode</p></td></tr><tr><td><strong>OtherAmount</strong></td><td>String</td><td>false</td><td>Cash back amount</td></tr><tr><td><strong>TipAmount</strong></td><td>String</td><td>false</td><td>Tip amount</td></tr><tr><td><strong>TaxAmount</strong></td><td>String</td><td>false</td><td>Tax amount, should be included in TransAmount</td></tr><tr><td><strong>DutyFreeAmount</strong></td><td>String</td><td>false</td><td>value of the tax exemption amount, should be included in TransAmount</td></tr><tr><td><strong>CurrencyCode</strong></td><td>String</td><td>true</td><td><p>Indicate currency code of transaction</p><p>156: RMB</p><p>840: USD</p><p>400: JOD</p></td></tr><tr><td><strong>ReqTransDate</strong></td><td>String (YYYYMMDD)</td><td>false</td><td>exp. “20201212”</td></tr><tr><td><strong>ReqTransTime</strong></td><td>String (hhmmss)</td><td>false</td><td>exp. “1614033”</td></tr><tr><td><strong>OriTransIndexCode</strong></td><td>String</td><td>false</td><td>Original request TransIndexCode</td></tr><tr><td><strong>OriTraceNum</strong></td><td>String</td><td>false</td><td></td></tr><tr><td><strong>OriInvoiceNum</strong></td><td>String</td><td>false</td><td>Original transaction InvoiceNum</td></tr><tr><td><strong>OriTransId</strong></td><td>String</td><td>false</td><td>Indicate original transaction id</td></tr><tr><td><strong>OriRrn</strong></td><td>String</td><td>false</td><td>Indicate original RRN</td></tr><tr><td><strong>OriTransDate</strong></td><td>String(YYYYMMDD)</td><td>false</td><td>Indicate original transaction date</td></tr><tr><td><strong>OriTransTime</strong></td><td>String(hhmmss)</td><td>false</td><td>Indicate original transaction time</td></tr><tr><td><strong>EnableReceipt</strong></td><td>boolean</td><td>false</td><td><p>false-Disable Receipt</p><p>true-Enable Receipt</p></td></tr><tr><td><strong>AppendingReceiptInfo</strong></td><td>String</td><td>false</td><td>Indicate message to be printed on receipt</td></tr><tr><td><strong>SkipConfirmProcedure</strong></td><td>boolean</td><td>false</td><td><p>false-Don not Skip</p><p>true-Skip Confirm Procedure</p></td></tr><tr><td><strong>EnableCancelInPayment</strong></td><td>boolean</td><td>false</td><td><p>true-Enable user cancel operation</p><p>false-Disable user cancel operation</p></td></tr><tr><td><strong>AdditionalInfo</strong></td><td>String</td><td>false</td><td></td></tr></tbody></table>

Request content sample:

```java
{
“TransType”: “Purchase”,
“TransIndexCode”: “112233”,
“TransAmount”: “10000”,
“CurrencyCode”: “840”,
“ReqTransDate”: “20210302”,
“ReqTransTime”: “144230”,
“OriTransId”: “”,
“OriRrn “: “”,
“EnableReceipt “: true,
“AppendingReceiptInfo “: “”,
“SkipConfirmProcedure”: false
}
```

### 8. Transaction Response Content

**Transaction Request is content is json format which contain request data as below:**

<table data-full-width="true"><thead><tr><th>NAME</th><th>FORMAT</th><th data-type="checkbox">MANDATORY</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td><strong>TransType</strong></td><td>String</td><td>true</td><td>Indicate transaction type to be performed.</td></tr><tr><td><strong>TransScheme</strong></td><td>String</td><td>false</td><td><p>Cooperation with TransType，used in specific schemes</p><p><a href="#a1.2_transaction_type">See A1.2 Transaction Scheme</a></p></td></tr><tr><td><strong>CallerName</strong></td><td>String</td><td>false</td><td>Caller name</td></tr><tr><td><strong>TransIndexCode</strong></td><td>String</td><td>false</td><td>Indicate Cashier trace number</td></tr><tr><td><strong>TransResult</strong></td><td>boolean</td><td>true</td><td><p>true: Success</p><p>false: Failed</p></td></tr><tr><td><strong>RespCode</strong></td><td>String</td><td>true</td><td>Response code from host server</td></tr><tr><td><strong>RespDesc</strong></td><td>String</td><td>true</td><td>Response message from host server</td></tr><tr><td><strong>ApprovalCode</strong></td><td>String</td><td>false</td><td>Approval code from host</td></tr><tr><td><strong>CardNum</strong></td><td>String</td><td>false</td><td></td></tr><tr><td><strong>EntryMode</strong></td><td>Int</td><td>false</td><td><p>0x01: Manual Entry</p><p>0x02: Swipe Entry(no CVV)</p><p>0x05: Contact ICC(with CVV)</p><p>0x07: Contactless</p><p>0x90: Swipe Entry(with CVV)</p><p>0x91: Contactless MSD</p><p>0x95: Contact ICC(no CVV)</p></td></tr><tr><td><strong>ExpiryDate</strong></td><td>String</td><td>false</td><td></td></tr><tr><td><strong>CardBrand</strong></td><td>String</td><td>false</td><td><p>exp.</p><p>Visa/MasterCard/Amex/Discover</p></td></tr><tr><td><strong>TransAmount</strong></td><td><p>String</p><p>[Mandatory for Sale/Refund]</p></td><td>true</td><td><p>“112233” means</p><p>1122.33(USD) 112.233(JOD)</p></td></tr><tr><td><strong>OtherAmount</strong></td><td>String</td><td>false</td><td>Cash back amount</td></tr><tr><td><strong>TipAmount</strong></td><td>String</td><td>false</td><td>Tip amount</td></tr><tr><td><strong>Balance</strong></td><td>String</td><td>false</td><td></td></tr><tr><td><strong>TaxAmount</strong></td><td>String</td><td>false</td><td>Tax amount, should be included in TransAmount</td></tr><tr><td><strong>DutyFreeAmount</strong></td><td>String</td><td>false</td><td>value of the tax exemption amount</td></tr><tr><td><strong>CurrencyCode</strong></td><td>String</td><td>false</td><td><p>Indicate currency code of transaction</p><p>156: RMB</p><p>840: USD</p><p>400: JOD</p></td></tr><tr><td><strong>CountryCode</strong></td><td>String</td><td>false</td><td></td></tr><tr><td><strong>DccOriCurrencyCode</strong></td><td><p>Integer</p><p>[Mandatory when DCC]</p></td><td>false</td><td>Original Request Currency Code to be converted</td></tr><tr><td><strong>DccOriAmount</strong></td><td><p>String</p><p>[Mandatory when DCC]</p></td><td>false</td><td>Original Request Amount</td></tr><tr><td><strong>DccFee</strong></td><td><p>String</p><p>[Mandatory when DCC]</p></td><td>false</td><td>DCC Fee of the transaction</td></tr><tr><td><strong>DccExchangeRate</strong></td><td><p>String</p><p>[Mandatory when DCC]</p></td><td>false</td><td>DCC exchange rate</td></tr><tr><td><strong>DccMarkUp</strong></td><td><p>String</p><p>[Mandatory when DCC]</p></td><td>false</td><td>DCC mark up</td></tr><tr><td><strong>DccFooterText</strong></td><td><p>String</p><p>[Mandatory when DCC]</p></td><td>false</td><td>DCC footer text</td></tr><tr><td><strong>TransDate</strong></td><td>String (YYYYMMDD)</td><td>true</td><td><p>Transaction date</p><p>exp. “20201212”</p></td></tr><tr><td><strong>TransTime</strong></td><td>String (hhmmss)</td><td>true</td><td><p>Transaction time</p><p>exp. “1614033”</p></td></tr><tr><td><strong>MID</strong></td><td>String</td><td>false</td><td>Merchant ID</td></tr><tr><td><strong>TID</strong></td><td>String</td><td>false</td><td>Terminal ID</td></tr><tr><td><strong>MerchantName</strong></td><td>String</td><td>false</td><td>Merchant Name</td></tr><tr><td><strong>MerchantAddress</strong></td><td>String</td><td>false</td><td>Merchant Address</td></tr><tr><td><strong>TraceNum</strong></td><td>String</td><td>false</td><td>Trace Number of payment app</td></tr><tr><td><strong>TransID</strong></td><td>String</td><td>false</td><td>Transaction ID returned from Host Server</td></tr><tr><td><strong>InvoiceNum</strong></td><td>String</td><td>false</td><td>Invoice Number of transaction</td></tr><tr><td><strong>RRN</strong></td><td>String</td><td>false</td><td>Retrieval Reference number returned from Host Server</td></tr><tr><td><strong>AuthCode</strong></td><td>String</td><td>false</td><td>Transaction Auth Code returned from Host Server</td></tr><tr><td><strong>OriTransIndexCode</strong></td><td>String</td><td>false</td><td>Original request TransIndexCode</td></tr><tr><td><strong>OriInvoiceNum</strong></td><td>String</td><td>false</td><td>Original transaction InvoiceNum</td></tr><tr><td><strong>OriTransId</strong></td><td>String</td><td>false</td><td>Indicate original transaction id</td></tr><tr><td><strong>OriRrn</strong></td><td>String</td><td>false</td><td>Indicate original RRN</td></tr><tr><td><strong>EmvAid</strong></td><td>String</td><td>false</td><td>Indicate EMV AID</td></tr><tr><td><strong>EmvAppName</strong></td><td>String</td><td>false</td><td>Indicate EMV app name</td></tr><tr><td><strong>EmvCryptogram</strong></td><td>String</td><td>false</td><td>Indicate EMV TC or ARQC</td></tr><tr><td><strong>EmvTVR</strong></td><td>String</td><td>false</td><td>Indicate EMV TVR</td></tr><tr><td><strong>AdditionalInfo</strong></td><td>String</td><td>false</td><td></td></tr><tr><td><strong>CardUniqueId</strong></td><td>String</td><td>false</td><td>Card unique ID is returned only when TransType is ReadCard.</td></tr></tbody></table>

### 9. Cancel Request Content

Cancel request content is empty.

### 10. Cancel Response Content

| **NAME**        | **FORMAT**                        | **DESCRIPTION**                                                                 |
| --------------- | --------------------------------- | ------------------------------------------------------------------------------- |
| **“cancelled”** | <p>boolean</p><p>\[Mandatory]</p> | <p>true: transaction cancelled.</p><p>False: transaction can’t be cancelled</p> |

## Annex 1

### A1.1 Transaction Type <a href="#a1.1_transaction_type" id="a1.1_transaction_type"></a>

| TransType                                                       | Description                                                                                |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Purchase**                                                    |                                                                                            |
| **PreAuth**                                                     |                                                                                            |
| **IncrementalAuth**                                             |                                                                                            |
| **AuthVoid**                                                    |                                                                                            |
| **AuthCompletion**                                              |                                                                                            |
| **BalanceInquiry**                                              |                                                                                            |
| **Reversal**                                                    |                                                                                            |
| **Refund**                                                      |                                                                                            |
| **Settle**                                                      |                                                                                            |
| **TipAdjust**                                                   | WorldPay only                                                                              |
| **ReadCard**                                                    | To get card information, simply pass the TransType, and the CardUniqueId will be returned. |
| *<mark style="background-color:blue;">Local transaction</mark>* |                                                                                            |
| **QueryTransaction**                                            | Query transaction result by OriTransIndexCode                                              |
| **PrintLast**                                                   |                                                                                            |
| **PrintTotal**                                                  |                                                                                            |
| **PrintDetail**                                                 |                                                                                            |
| **PrintParameter**                                              |                                                                                            |
| **GetPosInfo**                                                  |                                                                                            |
| **VerifyCardPan**                                               | Verify whether card number match original transaction                                      |

### A1.2 Transaction Scheme <a href="#a1.2_transaction_type" id="a1.2_transaction_type"></a>

| Scheme     | Description    |
| ---------- | -------------- |
| **Credit** | Credit card    |
| **Debit**  | Debit card     |
| **EBT**    |                |
| **ECS**    |                |
| **QR**     | QR transaction |
