Skip to main content
This guide describes how to integrate Alipay Web Payments for both Hong Kong and overseas merchants.
AlipayHK does not support the native Alipay checkout page.
For AlipayHK, merchants typically request a QR code / payment URL and embed it in the merchant page (e.g. as a QR code image or via an iframe).

​
Overview

Alipay Web Payments allow customers to complete a purchase by scanning a QR code (or opening a hosted payment URL). After payment confirmation, funds are deducted from the customer’s wallet and the result is returned to the merchant system.
  • Mainland China users pay in CNY; QFPay settles to merchants in the configured settlement currency.
  • Hong Kong users pay in HKD.
If return_url is provided, the customer is redirected back to the merchant website after payment.

​
HTTP Request

Endpoint POST /trade/v1/payment

​
Supported Pay Types

PayTypeDescription
801101Alipay Web Payment (Overseas)
801514Alipay Web Payment (Hong Kong)

​
Request Parameters

FieldTypeRequiredDescription
txamtInt(11)YesAmount in cents. Suggested > 200 to reduce risk control triggers.
txcurrcdString(3)YesCurrency (e.g. HKD, CNY). See Currencies.
pay_typeString(6)YesPayType (see table above).
out_trade_noString(128)YesUnique merchant order ID.
txdtmString(20)YesTimestamp YYYY-MM-DD HH:mm:ss.
expired_timeString(3)NoQR expiry (minutes). 5–120. (MPM only)
goods_nameString(64)NoProduct name (≤20 chars). Use UTF-8 if Chinese.
mchidString(16)NoRequired if provided by QFPay for your store setup.
udidString(40)NoDevice ID for reporting.
return_urlString(512)NoRedirect URL after successful payment.

​
Response Parameters

FieldTypeDescription
respcdString(4)Return code. 0000 = success; 1143/1145 = retry needed; others = failed.
resperrString(128)Error details (if any).
respmsgString(128)General response message.
syssnString(40)QFPay transaction ID.
out_trade_noString(128)Merchant order ID.
txamtInt(11)Amount (cents).
txdtmString(20)Request timestamp.
sysdtmString(20)Server timestamp (used for settlement cutoff).
pay_typeString(6)PayType used.
pay_urlString(512)Payment URL (render as QR code or embed in iframe).

​
Code Examples

Use the language tabs below. Replace the placeholders with your own credentials and values.
# coding=utf-8
import hashlib
import requests
import datetime

environment = "https://test-openapi-hk.qfapi.com"
app_code = "YOUR_APP_CODE"
client_key = "YOUR_CLIENT_KEY"

def make_req_sign(data, key):
    keys = sorted(list(data.keys()))
    parts = []
    for k in keys:
        parts.append(f"{k}={data[k]}")
    sign_str = ("&".join(parts) + key).encode("utf-8")
    return hashlib.md5(sign_str).hexdigest().upper()

current_time = datetime.datetime.now().replace(microsecond=0).strftime("%Y-%m-%d %H:%M:%S")

data = {
    "txamt": "10",
    "txcurrcd": "HKD",
    "pay_type": "801101",
    "out_trade_no": "01234567890123",
    "txdtm": current_time,
    # "mchid": "ZaMVg*****"  # include only if provided by QFPay
}

headers = {
    "X-QF-APPCODE": app_code,
    "X-QF-SIGN": make_req_sign(data, client_key),
}

r = requests.post(environment + "/trade/v1/payment", data=data, headers=headers)
print(r.json())

​
Sample Response

{
  "sysdtm": "2020-04-13 10:30:34",
  "paydtm": "2020-04-13 10:30:34",
  "txcurrcd": "HKD",
  "respmsg": "",
  "pay_type": "801101",
  "udid": "qiantai2",
  "txdtm": "2020-04-13 10:30:34",
  "txamt": "300",
  "resperr": "success",
  "out_trade_no": "4K35N374II7UJJ8RGIAE45O2CVHGHFF0",
  "syssn": "20200413000300020087033882",
  "respcd": "0000",
  "pay_url": "https://globalmapi.alipay.com/gateway.do?...",
  "chnlsn": ""
}

​
Notes

Render the QR code or iframe using pay_url.
Do not reuse out_trade_no across payments or refunds.
If respcd is 1143 or 1145, retry or query the transaction result using /trade/v1/query.