10. Order Create

2026-05-13 10:02

Bill Payment Order Creation

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).

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).
accountId	String	64	Yes	ID of merchant's user.
orderAmount	Amount	-	No	Order amount

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`.

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	Yes	Order amount
acquiringSite		String	64	no	Acquiring site. - `aboss` - `ipay`
redirectUrl		String	256	no	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.
orderDetail		String	-	Yes	Order detail. Need to convert Json to String format. See OrderDetail below.

OrderDetail

Field	Type	Length	Required	Description
notifyUrl	String	64	Yes	The URL for receiving asynchronous notifications after the payment is completed.
orderTitle	String	1024	Yes	Brief description of the transaction. Special characters are not supported.

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.

Samples

Request

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

Response

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\"}"
}

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).