Skip to main content

Documentation Index

Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt

Use this file to discover all available pages before exploring further.

Supported Terminal Models
  • LANDI A8 / A8S — All payment methods supported
  • PAX A920 — QR code payments only

​
1. POS-KEY

POS-KEY is a secret key used to encrypt transaction data. It is generated via the Haojin App. Encryption is enabled by default. Merchants may toggle encryption on/off or regenerate the POS-KEY from the Merchant Portal (MMS). After changes, the POS device must refresh via the Haojin App.

​
Refresh POS-KEY

Haojin App → My → Settings → POS-Key → Generate

​
Check POS-KEY

Merchant Portal → Settings → Device Settings → POS Key Mgmt

​
2. Encryption

  • Algorithm: AES
  • Key: POS-KEY
  • IV: qfpay202306_hjsh
  • Output: Base64 encoded

​
3. Request Payload Format

AttributeMandatoryTypeDescription
amtYesDoubleTransaction amount (e.g. 10.1 = HKD $10.10)
func_typeYesStringInstruction code
channelYesStringWallet/payment method
out_trade_noNoStringMerchant reference ID
camera_idNoInteger0 = back camera (default), 1 = front camera
payment_timeoutNoIntegerPayment timeout (seconds)
wait_card_timeoutNoIntegerCard input timeout (default 120s)

​
3.1 Payment

QR Mode
  • MPM / CPM auto-selected based on last usage
Camera
  • 0 back (default)
  • 1 front
Timeout
  • Card: time to tap/swipe
  • Wallet/QR: time to confirm
  • PayMe max timeout: 120 seconds
Scan Type
  • QRCODE_PAY
  • SCAN_PAY
Return to Home
  • 0 stay on result screen (default)
  • 1 return to home after transaction
{
  "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"
}

​
3.2 Refund / Void

AttributeMandatoryTypeDescription
orderIdYesStringQFPay transaction ID
refund_amountNoStringPartial refund supported
allow_modify_flagNoInteger0 fixed, 1 allow change
For Visa, Mastercard, UnionPay Card, and Amex, same-day refunds 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 Summary

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

​
3.5 Transaction Inquiry

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

​
3.6 Cancel Request

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

​
4. Signature Generation

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

// sort keys alphabetically
format_content={amt=100,channel='card_payment',func_type=1001,out_trade_no='456799999999'}

// generate digest
digest=md5(format_content + pos_key)
If encryption is enabled:
  1. Encrypt content using AES
  2. Generate digest from encrypted payload

​
5. Field Definitions

​
func_type

ValueDescription
1001Payment
1002Refund
3001Print receipt
3002Print summary
4001Inquiry
5001Cancel

​
channel (Payment Method)

ValueDescription
card_paymentCredit card
wxWeChat Pay
alipayAlipay
paymePayMe
unionUnionPay
fpsFPS
octopusOctopus
unionpay_cardUnionPay Card
amex_cardAmerican Express

​
6. Response Format

{"respcd":"6000","data":"{...}","respmsg":"OK","resperr":""}

​
Response Codes

CodeMeaning
6000Success
6001Cancelled
6002Error
4003Denied
5001Decryption failed

​
7. Communication Methods

​
USB

Connect POS to register via USB. Payload must be AES encrypted and parsed according to protocol.

​
HTTP / HTTPS

  • Default port: 9001
  • POST JSON payload
  • AES encrypted
Endpoints:
OperationPath
Trade/api/pos/trade
Refund/api/pos/cancel
Print receipt/api/pos/print_receipt
Print summary/api/pos/transaction_info
Inquiry/api/pos/query_transaction
For HTTPS setup, please refer to the ECR Integration HTTPS documentation.

​
TCP

  • Default port: 9002
  • Socket communication
  • AES encrypted

​
8. USB Protocol Overview

Start indicator: 0x2f6e
Payload max: 65536 bytes
Recommended: ≤ 1024 bytes
0x2f6e represents the ASCII string “/n” — not a newline.

​
9. AES Encryption

  • AES-128 CBC
  • PKCS5 padding
  • 16-byte key
  • Required for request & response

​
10. Serial Port Settings

SettingValue
Baud rate9600
Stop bit1
Parity0
Data bits8
Flow controlOff

​
11. USB-Serial Chip Support

ChipSupported
PL2303 HXDYes
CH340No
FT232No
Chip support applies only to USB communication mode. HTTP / HTTPS and TCP integrations are unaffected.