ECR integration technical specification

note

4.33.24 update 1、After transaction and refund finished add moveToBack to move to Home Page, type int defult 0 moveToBack: 0:no need to Home Page 1:need back to Home Page

note

Support Terminal Model:

Landi A8 & A8S, All Payment Methods Supported. PAX A920, QRCode Payment Only.

1. POS-KEY

POS-KEY is a secret key used to encrypt and decrypt the data. It is generated by Haojin App.

The default POS-KEY is f46b1f08bec1f39104792cc79ec9aacd

The default encrpytion is ON.

There is an option to switch on/off on merchant portal (MMS) or refresh POS-KEY. And, Haojin App refresh is required to be effective

Steps to refresh POS-KEY Login Haojin App -> My -> Settings -> POS-Key -> generate

Steps to check POS-KEY Login Shop Management Platform-> Settings -> Devices Settings -> POS Key Mgmt tab

2. Encryption

All data is encrypted by AES. The key is POS-KEY and the IV is qfpay202306_hjsh

The data is encoded by Base64 after encryption.

3. Request payload format

Attribute	Mandatory	Type	Description
amt	Yes	Double	Amount e.g. $10.1 => 10.1
func_type	Yes	String	Instruction code
channel	Yes	String	Wallet name, refer to Channel list
out_trade_no	No	String	Merchant reference. if not passed, the out_trade_no won't be passed
camera_id	No	Integer	can select using front camera or back camera in QR code payment CPM mode 0: back camera (default), 1: front camera
wait_card_timeout	No	Integer	can set waiting time, default 120 seconds, trigger timeout exception.

3.1 Payment

note

For QR code payment, MPM/CPM mode is automatically selected base on last usage.

Front camera or back camera can be selected to use by parameter camera_id

Time to wait for payment in payment page can be set by parameter wait_card_timeout

payment_timeout : （1）、When set payment_timeout in card payment ，this time is the max time waiting for using card （2）、For other payment payment_timeout，this field is the max time for that transaction type int，value greater than 0

scan_type:specific scan method QRCODE_PAY SCAN_PAY

moveToBack:After the payment and refund process, it will support back to Home Page.This field is not necessary, default not back to Home Page. 0: No need back to Home Page 1:need back to Home Page

{
    "content": {
        "amt": 100, 
        "camera_id":0, 
        "channel": "card_payment",
        "func_type": 1001, 
        "moveToBack": 1,
        "out_trade_no": "456799999999",
        "wait_card_timeout":120,
        "scan_type": "SCAN_PAY"
    },
    "digest":"76b9186077cdc2bc5d78ae921309811d"
}

For inquiry the transaction result, please use the Inquire API

2.2 Refund / Void

no password input is required in app when initialize refund request

specific parameters

Attribute	Mandatory	Type	Description
orderId	Yes	String	QFPay transaction Id
refund_amount	No	String	the default refund amount is the refundable amount of the order, support partial refund
allow_modify_flag	No	Integer	0: Not allow modification of refund amount (default value) 1: allow modification of refund amount

note

for Visa/Mastercard, Unionpay Card and American Express Card, the amount of same day refund must be full amount

{
     "content": {
        "allow_modify_flag":1, 
        "func_type": 1002,
        "orderId": "order_id",
        "refund_amount": "0.05",
        "moveToBack": 1
    },
     "digest": "9C8E9FB05C7C24B6CA04EBFA1263EF41"
}

3.3 Print receipt

{
    "content": {"orderId": "12345678","func_type": 3001},
    "digest":"79fd145311d54d03e4e685d50f15dd7f"
}

3.4 Print transaction summary

{
    "content": {"func_type": 3002},
    "digest":"79fd145311d54d03e4e685d50f15dd7f"
}

3.5 Transaction inquiry by order Id

new paramter out_trade_no is supported

{
     "content": {"orderId": "1234567890","func_type": 4001},
     "digest":"99CE8BF9C7304AC964522D10F51660B4"
}

3.6 Cancel trade/refund request

{
    "content": {"func_type": 5001},
    "digest": "99CE8BF9C7304AC964522D10F51660B4"
}

content：data request payload digest: signature of data request payload (content), sort the parameters in alphabetical ascending order and concat them in key=value format, use md5 algorithm to get hash value which is signature

Generate signature

sample of generate signature

// original payload
content={"amt":100,"channel": "card_payment","func_type":1001,"out_trade_no":"456799999999"} 

// sorted keys in alphabetical ascending order
format_content={amt=100,channel='card_payment',func_type=1001,out_trade_no='456799999999'} 

// encryption
// !! if the value is empty, pass '' (empty string) instead
digest=md5(format_content + pos_key)
digest=md5({amt=100,channel='card_payment',func_type=1001,out_trade_no='456799999999'}f46b1f08bec1f39104792cc79ec9aacd) 

if encryption is enabled, the above payload will be encrypted by AES at content, and the digest will be calculated based on the encrypted payload.

for example

{
    "content": "{func_type: 3002}",
    "digest":"79fd145311d54d03e4e685d50f15dd7f"
}

4. Fields explanation

1、 func_type : business type
    (1) 1001 Trade
    (2) 1002 Refund
    (3) 3001 Print receipt
    (4) 3002 Print transaction summary
    (5) 4001 Transaction inquiry
    (6) 5001 Cancel trade/refund request

2、channel: payment method
    (1) 、card_payment  Visa/Mastercard
    (2) 、wx            WeChat Pay
    (3) 、alipay        Alipay
    (4) 、payme         PayMe
    (5) 、union         UnionPay QuickPass
    (6) 、fps           FPS
    (7) 、octopus       Octopus
    (8) 、unionpay_card Unionpay Card
    (9) `amex_card`     American Express Card

3、amt: Transaction amount

4、orderId: Transaction reference number, the same as out_trade_no

5. Response format

{\"respcd\": \"6000\",\"data\": \"{"aaaaaa"}\",\"respmsg\": \"xxxxxxxxxx\",\"resperr\":\"xxxxxxxxxx\"}

1、respcd: response code
    （1）、"4003"，POS-KEY is invalid
    （2）、"5001"，Decryption failed
    （3）、"4004"，Request method is incorrect, may use POST request
    （4）、"4005"，Other errors
    （5）、"4006"  Incorrect parameter(s)
    （6）、"5001"，Decryption failed
    （7）、"6000"  request succeed
    （8）、"6001"  request cancel
    （9）、"6002"  request error

2、respmsg：Response message
3、resperr：Error message
4、data:response data from trade or refund request
    (1) data fields in trade response：
            respcd;response code
            resmsg;response message
            reserr;response error message
            mchntnm;merchant name
            sysdtm;QF system time
            userid;store Id
            busicd;business code
            txamt;transaction amount
            txcurrcd;transaction currency
            chnlsn;channel serial number
            paydtm;wallet payment time
            udid;user id
            syssn;QF Order Id
            clisn;client serial number
            out_trade_no；merchant order Id
            cardscheme;card scheme, e.g. VISA, MASTERCARD, UNIONPAY, AMEX
    (2) data field in refund response：
            respcd;response code
            resmsg;response message
            reserr;response error message
            sysdtm;QF system time
            paydtm;wallet payment time
            txcurrcd;transaction currency
            txdtm;trsnaction time
            orig_syssn;original QF order Id
            out_trade_no;merchant order Id
            syssn;QF order Id
            chnlsn;channel serial number
            txamt;transaction amount
            originTxamt;original transaction amount
    (3) data field in transaction inquiry response:
            server_time;QF server time
            cancel;cancel status
            clisn;client serial number
            opuid;operator id
            syssn;QF Order ID
            tradetp;trade type, e.g. payment, refund
            sysdtm;QF system time
            txcurrcd;transaction currency
            origssn;original QF Order Id
            customer_source;customer source, e.g. HK, INT
            opuser;operator name
            nickname;store name
            allow_refund_amt; refundable amount
            desc;description
            txamt;transaction amount
            busicd;paytype code
            respcd;response code
            origbusicd;original transaction paytype code
            chnlsn;wallet order Id
            cardscheme;card scheme, e.g. VISA, MASTERCARD, UNIONPAY, AMEX
            cardno;masked card number, e.g. 520000******1096
            cardtype;card type, e.g. CREDIT, DEBIT
            batchno;QF batch number
            refno;QF reference number

6. USB data transmission method

1. Connect the POS to the cash register via USB cable.
2. follow the USB communication protocol to construct the data. See the ninth article for details: "Cash register & Pos communication protocol".
3. Data response. The received data needs to be parsed according to the communication protocol, and then the data message is obtained, and then decrypted by AES.

7. HTTP protocol

1. HTTP data transmission method requires POS host IP address and port. The default port of the HTTP method is 9001.
2. Data message format: (1) Encrypt the data message through AES (2) Initiate the request through the HTTP Post request
3. Request API (1) Trade: /api/pos/trade (2) Refund: /api/pos/cancel (3) Print receipt: /api/pos/print_receipt (4) Print transaction summary: /api/pos/transaction_info (5) Transaciton inquiry: /api/pos/query_transaction (6) Cancel trade/refund request: /api/pos/cancel_request
4. The request header needs to be set. The request Content-type format is: application/json
5. The request result needs to be decrypted by AES to obtain the response message data

8. TCP protocol

1. The HTTP data transmission method requires POS host and port. The default port of the HTTP method is 9002.
2. Cash register connects to POS through socket connection
3. Data is transmitted through socket. The data format is the encrypted data of the data message after AES encryption.
4. The result of the request needs to be decrypted by AES to obtain the response message data

9. Cash register & Pos communication protocol (USB)

9.1 Use scenario

The cash register and the smart POS device communicate through the serial port or Bluetooth to realize the cash register through the Haojin merchant App on the smart POS to collect and cancel the transaction.

9.2 Communication method

Serial port.

Through the Micro USB interface on the smart POS device or by borrowing the base to convert to USB Host mode, connect to the cash register via USB to serial cable.

USB is more stable than Wifi, secure, and easy to deploy.

9.3 Payload format

Field name	content	Description	Length
Start indicator	0x2f6e	start of payload	2 Bytes
version	0x01	version (static)	1 Byte
payload type	0x10 0x20 0x30	request response response error	1 Byte
response reference number	0x01 ~ 0x7f	used for request/response, payload splitting / concatenation incremental for each, in loop	1 Byte
payload length		total bytes from Start indicator to End indicator	2 Bytes
payload length (data segment)		total bytes of data segment	2 Bytes
data segment		data segment, utf-8 encoding	non static
End indicator	0x2f6e	indicate end of the payload	2 Bytes

9.4 detail explanation

Start indicator and end indicator

In order to avoid the situation that a data packet is split into multiple data blocks due to hardware reasons during communication, resulting in the inability to obtain the contents of the packet normally. The sender adds the start and end characters (0x2f6e) to each packet when sending the packet.

After the receiver receives the packet, it will check whether the first two bytes of the packet are the start character (0x2f6e). If not, an error packet (0x31) will be responded. Otherwise, continue to traverse the subsequent bytes until the end character.

warning

0x2f6e is the hexadecimal representation of /n (string, NOT the carriage return) in ASCII encoding

Payload error type

error type	description
0x30	unknown
0x31	format error
0x32	validation error
0x33	data segment decrypt error
0x34	data segment format error
0x35	data segment packets error

request and response

When the receiver receives the request packet (packet type is 0x10), it needs to send a response packet to inform the sender of the result of receiving the packet. If the validation is successful, the response packet type is 0x20. If the validation fails, the response packet type is 0x32. The response packet number is the same as the request packet number.

response timeout

Response timeout is 1000ms, if timeout, the request is considered failed, and the device is disconnected.

payload length

1. total length of the payload, from start indicator to end indicator
2. payload length of data segment
3. since the payload length is 2 bytes, the maximum length of the data segment is 65536 bytes
4. it is recommended to keep the data segment length within 1024 bytes, if the data segment is too long, it should be split into multiple packets

Data pack splitting and concatenation

When sender splits the data segment into multiple packets, the packet number is the same, and the packet length is the total length of the data segment. The receiver needs to wait for the subsequent packets with the same packet number until the packet length is equal to the total length of the data segment, and then send the response packet.

The receiver waits for the timeout of multiple packets to be 500ms. After the timeout, the previously received packets are discarded. If subsequent packets with the same number are received, an error (0x35) response packet is sent.

Data encryption

The sender and receiver need to encrypt the valid data using the AES algorithm. The key is allocated by the service provider.

Key length 16 bytes 128 bits

Key offset ***** Algorithm mode CBC (Cipher Block Chaining) encryption block chain Padding method PKCS5Padding

Serial port settings

Baud rate: 9600 Stop bit: 1 Parity bit: 0 Data bit: 8 Flow control: off

USB to serial port line chip type supported

PL2303 HXD supported CH340 not supported FT232 not supported

The above chip types are the most common USB to serial port chips on the market. The stability and price of the three chips are the same, FT232>CH340>PL2303

Sample data

Sample data is as follows:

{\"content\":\"{\\\"amt\\\":100,\\\"channel\\\":\\\"wx\\\",\\\"funcType\\\":1,\\\"mode\\\":1}\",\"digest\":\"2f0c4683e25a7b9407265033070e9034\"}

complete data request content(Hexadecimal format):

2f6e011001007f00747b22636f6e74656e74223a227b5c22616d745c223a3130302c5c226368616e6e656c5c223a5c2277785c222c5c2266756e63547970655c223a312c5c226d6f64655c223a317d222c22646967657374223a223266306334363833653235613762393430373236353033333037306539303334227d2f6e