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

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.

STX	VERSION	CTRL	LEN	CONTENT	ETX	BCC
0x02	0x02	(4 bytes)	(2 bytes)	(LEN bytes)	0x03	(1 byte)

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:

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

Request content sample:

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

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

9. Cancel Request Content

Cancel request content is empty.

10. Cancel Response Content

NAME	FORMAT	DESCRIPTION
“cancelled”	boolean [Mandatory]	true: transaction cancelled. False: transaction can’t be cancelled

Annex 1

A1.1 Transaction Type

TransType	Description
Purchase
PreAuth
AuthCompletion
BalanceInquiry
Reversal
Refund
Settle
Local transaction
QueryTransaction	Query transaction result by OriTransIndexCode
PrintLast
PrintTotal
PrintDetail
PrintParameter
GetPosInfo
VerifyCardPan	Verify whether card number match original transaction

A1.2 Transaction Scheme

Scheme	Description
Credit	Credit card
Debit	Debit card
EBT
ECS
QR	QR transaction