10. Order Create

2026-06-07 17:46

Bill Payment Order Creation

After payment flow done AlipayHK backend will call alipay.intl.acquiring.common.notify.pay to merchant backend

1. API Overview

Property	Value
Interface Name	`alipay.intl.hk.wallet.charge.order.create`
Type	API
Processing Method	Synchronous
Description	Create a payment order for bill payment or single payment (e.g., stored-value card top-up).

2. Request Parameters

Field	Type	Length	Required	Description
requestId	String	64	Yes	Unique request ID. Used for idempotency: the same requestId returns the same merchant order ID.
userId	String	64	Conditional	AlipayHK user ID. For keys 「openId」 & 「userId」, one of them must have content
openId	String	64	Conditional	User OpenID For keys 「openId」 & 「userId」, one of them must have content
merchantAccountId	String	64	Yes	Merchant account ID.
subMerchantId	String	64	No	Sub-merchant ID.
orderType	String	64	Yes	Order type:- `SINGLE_PAYMENT_ORDER` — Single payment (e.g., stored-value card top-up)- `BILL_ORDER` — Bill payment (for linked bills)
businessId	String	64	No	Business ID provided by the merchant (e.g., plan ID for stored-value card top-up).
source	String	16	No	Payment source:- `BY_TEMPLATE` — Template-based single payment- `NORMAL` — Standard entry
paymentInfo	String	JSON	No	Template-based single payment form data. Required when source=BY_TEMPLATE. See 2.2 PaymentInfo below.
accountId	String	64	Yes	ID of merchant's user.
orderAmount	Amount	-	No	Order amount
bills	List	512	No	List of bills to pay. See 2.3 Bill below.

2.1 Amount

Field	Type	Length	Required	Description
value	String	64	Yes	Amount in cents (e.g., `"1000"` = 10.00 HKD).
currency	String	1024	Yes	Currency code: `HKD`.

2.2 PaymentInfo

Template-based single payment form submission. Structure:

copy
{
  "formCode": "form_code_value",
  "formValue": {
    "fieldCode1": "fieldValue1",
    "fieldCode2": "fieldValue2",
    "fieldCode3": "fieldValue3"
  }
}

The formCode and field codes correspond to the template definition configured via the Bill Bind Template API.

2.3 Bill

Field	Type	Description
billRef	String	Merchant bill reference number.
amount	String	Bill amount (in cents).
currencyCode	String	Currency code (e.g., `HKD`).

3. Request Example

Bill Payment (source=NORMAL)

copy
{
  "requestId": "req_20260508_001",
  "openId": "o123456789abcdefgh",
  "merchantAccountId": "2160400000002012",
  "subMerchantId": "4555219051",
  "orderType": "BILL_ORDER",
  "accountId": "88701108",
  "orderAmount": {
        "value": "100.00",
        "currency": "HKD"
  }
}

Single Payment (source=BY_TEMPLATE)

copy
{
    "requestId": "req_20260508_002",
    "openId": "o123456789abcdefgh",
    "merchantAccountId": "2160400000002012",
    "orderType": "SINGLE_PAYMENT_ORDER",
    "source": "BY_TEMPLATE",
    "paymentInfo": {
        "formCode": "aaa",
        "formValue": {
            "billNo": "1234567890123456",
            "name": "John Doe",
            "amount": "5000"
        }
    },
    "bills": [{
        "billRef": "123456",
        "amount": "10",
        "currencyCode": "HKD"
    }, {
        "billRef": "567890",
        "amount": "22",
        "currencyCode": "HKD"
    }]
}

4. Response Parameters

Field	Sub-field	Type	Length	Required	Description
result		Object	-	Yes	Result object.
	resultCode	String	64	Yes	Result code: `SUCCESS` or `FAIL`.
	resultStatus	String		Yes	Result code: `S` or `F`.
	resultCodeId	String	10	Yes	0000
	resultMessage	String	256	No	Result message (e.g., failure reason).
orderId		String	64	Yes	Merchant order ID.
orderAmount		Amount	64	No	Order amount
acquiringSite		String	64	no	Acquiring site. - `aboss` - `ipay`
redirectUrl		String	256	Optional	Redirect URL. Returned when the user needs to be redirected to the operator's page for payment. Returned for template payment and linked bill payment.
orderStr		String	1024	Optional	Used to invoke the AlipayHK app payment cashier for the user to complete the payment. Not required for auto-payment or auto-recharge scenarios.
orderDetail		String	-	Optional	Order detail. See OrderDetail below.

OrderDetail

copy
{
  "notifyUrl": "https://example.com/notify",
  "orderTitle": "China Unicom Top-up 20 HKD",
  "merchant": "{\"merchantId\":\"2160xx\",\"subMerchantId\":\"123\",\"merchantName\":\"测试商户\",\"merchantEnglishName\":\"test merchant\",}"
}

5.Response Example

Scenario 1: The payment is automatically processed in the backend.

copy
{
  "result": {
    "resultStatus": "S",
    "resultCodeId": "0000",
    "resultCode": "SUCCESS",
    "resultMessage": "success"
  },
  "orderId": "order_auto_topup_001",
  "orderAmount": {
    "value": "2000",
    "currency": "HKD"
  },
  "orderDetail": "{\"notifyUrl\":\"https://merchant.example.com/notify\",\"orderTitle\":\"Auto Payment - Mobile Recharge\"}"
}

Scenario 2: The user completes the payment in-app.

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultCodeId": "0000",
        "resultMessage": "SUCCESS"
    },
    "orderId": "ahk260513111548157_M_1",
    "orderDetail": "{\"notifyUrl\":\"https://domain.com/alipay-aboss/notify/online/12345\",\"orderTitle\":\"CMHK Postpaid\",\"merchant\":\"{\\\"merchantId\\\":\\\"2088031633012345\\\",\\\"subMerchantId\\\":\\\"4555212345\\\",\\\"merchantName\\\":\\\"中國移動\\\",\\\"merchantEnglishName\\\":\\\"China Mobile\\\"}\"}",
    "orderInfo": "_input_charset=UTF-8&currency=HKD&notify_url=https%3A%2F%2Fdomain.com%2Falipay-aboss%2Fnotify%2Fonline%2F12345&order_create=1778640642435&out_trade_no=ahk260513111548157_M_1&partner=2088031633012345&payment_inst=ALIPAYHK&product_code=NEW_WAP_OVERSEAS_SELLER&secondary_merchant_id=2088031633012345&secondary_merchant_industry=4814&secondary_merchant_name=China%20Mobile%20Hong%20Kong%20Company%20Limited&service=create_forex_trade_wap&subject=CMHK%20Postpaid&timeout_rule=15m&total_fee=98&sign=31f8ecbd511fcb54948a69e5de612345&sign_type=MD5",
    "orderAmount": {
        "value": "9800",
        "currency": "HKD"
    },
    "acquiringSite": "aboss"
}

Scenario 3: Redirect the user to the merchant page to complete the process.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success"
  },
  "orderId": "ahk24112264158830_P_1",
  "orderAmount": {
    "value": "5000",
    "currency": "HKD"
  },
  "acquiringSite": "ipay",
  "redirectUrl": "https://xxxxxxx",
  "orderDetail": ""
}

5.1 Result Codes

Result Code	Status	Description	Action
SUCCESS	S	Request processed successfully.	Proceed with payment flow.
PARAM_ILLEGAL	F	Invalid request parameters (e.g., non-numeric input, invalid date).	Check and correct request parameters.
PROCESS_FAIL	F	General business failure. Do not retry with the same parameters.	Review the error message and adjust.
UNKNOWN_EXCEPTION	U	API failed due to an unknown reason.	Retry with a new requestId.

Important Notes

Idempotency: The requestId is used as the idempotency key. Submitting the same requestId returns the same order. If the associated order has expired, an error will be returned.
Order Expiry: Each order has a validity window. Payment must be completed within this period.
Retry Logic: On the AlipayHK side, if the order creation API call or auto-debit fails, the system retries with a new requestId later (e.g. every hour).