Gateway Pre-pay
Description
Used in "gateway payment" scenarios: the merchant backend does not pre-select a payment method. Instead, it creates a gateway order and gets an H5 landing URL and a mini-program mapping URL, then routes users to the platform-hosted cashier or aggregate QR page based on their device.
Applies to:
- Cashier (
cashier): platform-hosted multi-method selection page - Aggregate QR (
aggregate): one code, multi-wallet auto-detection
Request
POST /unipay/gateway/pre-pay
- Auth: RSA signature (
@PaymentVerify) - Response:
DaxResult<GatewayPrePayResult>
Parameters
Common params same as Pay - Common Parameters. Business parameters:
| Parameter | Type | Required | Max | Description |
|---|---|---|---|---|
| bizOrderNo | string | Yes | 100 | Merchant order number |
| title | string | Yes | 100 | Order title |
| description | string | No | 50 | Order description |
| amount | long | Yes | — | Amount in cents (min 1, max 9999999999) |
| gatewayPayType | string | Yes | 32 | Gateway type: cashier (unified cashier) / aggregate (aggregate QR) |
| notifyUrl | string | No | 256 | Async notification URL |
| returnUrl | string | No | 256 | Sync redirect URL |
| attach | string | No | 512 | Merchant custom data (returned as-is) |
| extraParam | string | No | 2048 | Channel-specific extra params (JSON) |
| expiredTime | string | No | — | Expiry time (yyyy-MM-dd HH:mm:ss, GMT+8) |
| storeNo | string | No | 64 | Store number |
| goodsDetail | object[] | No | — | Goods detail list |
Example
json
{
"mchNo": "M200000001",
"appId": "APP001",
"reqId": "REQ20241201010",
"reqTime": "2024-12-01 12:00:00",
"sign": "Base64Signature",
"bizOrderNo": "ORDER20241201001",
"title": "Test Product",
"amount": 100,
"gatewayPayType": "cashier",
"notifyUrl": "https://your-domain.com/notify",
"returnUrl": "https://your-domain.com/return"
}Response
DaxResult<GatewayPrePayResult>, data fields:
| Field | Type | Description |
|---|---|---|
| orderNo | string | Platform gateway order number (used for subsequent query/sync) |
| bizOrderNo | string | Merchant order number |
| status | string | Business status (GatewayOrderStatusEnum; initial wait_pay) |
| h5Url | string | H5 landing URL (/cashier/{orderNo} for cashier, /aggregate/{orderNo} for aggregate) |
| miniUrl | string | Mini-program mapping URL (/cm/{orderNo} for cashier, /am/{orderNo} for aggregate); launched through a platform normal-link QR rule |
| expiredTime | string | Expiry time (UTC) |
Example
json
{
"code": 0,
"msg": "success",
"data": {
"orderNo": "G2024120112345700001",
"bizOrderNo": "ORDER20241201001",
"status": "wait_pay",
"h5Url": "https://your-domain.com/cashier/G2024120112345700001",
"miniUrl": "https://your-domain.com/cm/G2024120112345700001",
"expiredTime": "2024-12-01T04:30:00Z"
},
"sign": "Base64Signature",
"resTime": "2024-12-01T04:00:00Z",
"reqId": "REQ20241201010"
}Next Steps
- Merchant backend returns
h5UrlandminiUrlto frontend; browsers useh5Url, while mini-program normal-link QR codes useminiUrl. cashiermaps/cm/{orderNo}to the unified cashier mini-program;aggregatemaps/am/{orderNo}to the aggregate mini-program.- After the user pays on the gateway page, the platform notifies the merchant via
notifyUrl(eventpay.success). - Merchant may also actively query order status via Gateway Query.
WeChat normal-link QR configuration
Configure normal-link QR rules in the WeChat Mini Program backend:
/cm/*→pages-weixin/gateway-cashier/index(unified cashier mini-program)/am/*→pages-weixin/aggregate-pay/index(aggregate payment mini-program)
When entering from a normal-link QR code, WeChat places the complete URL in options.q; the pages extract the platform gateway order number from /cm/{orderNo} or /am/{orderNo}.