Collection order creation and queries: fields, amounts and order states
Your server first saves a local business order, then creates the collection order. If a request times out or the payment result is unknown, query the original merchant order number. Both operations require the merchant number, a current millisecond timestamp and a server-generated signature.
Contents
Order creation: POST JSON
Example URL: https://gateway.example.com/api/pay/collect/create; method: POST; request header: Content-Type: application/json; character encoding: UTF-8. Replace the example domain with the gateway actually enabled for your account.
| Field | Required | Value requirements |
|---|---|---|
mchId | Yes | Your merchant number; the example uses a string. |
wayCode | Yes | An enabled channel or aggregate code; the example uses a string. |
outTradeNo | Yes | Merchant order number, unique within the merchant account and associated with the local order. |
amount | Yes | Order amount in fen; the integer 1000 represents 10.00 yuan. |
currencyCode | No | Currency; the default is CNY。 |
notifyUrl | Yes | Your asynchronous notification URL, for example https://merchant.example.com/pay/notify。 |
subject | No | Product title; include it in signing if submitted. |
body | No | Product description; include it in signing if submitted. |
clientIp | No | Client IP, supplied according to the actual scenario. |
reqTime | Yes | Current millisecond timestamp; the example uses an integer. |
sign | Yes | Lowercase MD5 signature generated by the backend; exclude it from its own signature calculation. |
Your server determines the amount from trusted order records instead of directly trusting the price submitted by the frontend. Store order amounts as integer fen so that 10.00 yuan is not submitted as 10 fen, and avoid unhandled binary floating-point values in amount calculations.
Creating an order: field example
All identity and signature values in the JSON are placeholders; reqTime must be a current millisecond integer in a real request. Recalculate the signature before submitting.
{
"mchId": "MERCHANT_ID",
"wayCode": "80001",
"outTradeNo": "DEMO_COLLECT_001",
"amount": 1000,
"currencyCode": "CNY",
"notifyUrl": "https://merchant.example.com/pay/notify",
"subject": "DEMO_PRODUCT",
"reqTime": "CURRENT_UNIX_MILLISECONDS",
"sign": "RECOMPUTE_ON_YOUR_SERVER"
}import os
import time
from wenfupay_collect_sign import sign_collect
payload = {
"mchId": os.environ["MERCHANT_ID"],
"wayCode": "80001", # Use a code enabled for your merchant.
"outTradeNo": "YOUR_UNIQUE_ORDER_NO",
"amount": 1000, # 1000 cents = CNY 10.00.
"currencyCode": "CNY",
"notifyUrl": "https://merchant.example.com/pay/notify",
"reqTime": int(time.time() * 1000),
}
payload["sign"] = sign_collect(payload, os.environ["MD5_SECRET"])
# Send payload as JSON from your server to:
# API_BASE_URL + "/api/pay/collect/create"curl --request POST "$API_BASE_URL/api/pay/collect/create" \
--header "Content-Type: application/json; charset=UTF-8" \
--data @collect-create.jsonDownload the Python signing function used in the examples; for the calculation rules, see MD5 signing and verification。
Querying an order: sign first, then encode the query string
import os
import time
from urllib.parse import urlencode
from wenfupay_collect_sign import sign_collect
params = {
"mchId": os.environ["MERCHANT_ID"],
"outTradeNo": "YOUR_EXISTING_ORDER_NO",
"reqTime": int(time.time() * 1000),
}
# Alternative lookup: replace outTradeNo with platform_order_no.
params["sign"] = sign_collect(params, os.environ["MD5_SECRET"])
query_url = (
os.environ["API_BASE_URL"].rstrip("/")
+ "/api/pay/collect/query?" + urlencode(params)
)
# Send a server-side GET. Do not create another order on a timeout.Choosing Alipay, WeChat and channel codes
80001 is the Alipay aggregate code, and 90001 is the WeChat aggregate code. You may also use an assigned actual channel code. Aggregation selects only from linked candidate channels that the merchant is authorized to use and that are enabled; it does not make every channel automatically available to every merchant.
The backend maps payment options in your product to an enabled wayCode. Technical staff confirm the available codes, channel restrictions and testing procedure; the frontend does not need to know the internal routing configuration.
Aggregate routing may try another candidate only when the upstream channel explicitly confirms that the request was not accepted. It does not blindly switch on a timeout, exception or uncertain result. Your system should also query the original order first to avoid creating multiple orders that might all be paid.
Connect the order response to your payment page
The top-level JSON response contains code、message、data and sign. In a normal example, code set to 0;data contains duplicate、id、platformOrderNo、orderStatus、payUrl、channelErrorMessage。
Save the platform order number for queries, notification matching and reconciliation. Show a payment entry only when you have a genuinely valid payUrl ; it may be empty, so do not construct a cashier URL yourself. Validate the link scheme and destination domain, and configure the allowlist during technical integration.
code=0 does not mean funds have arrived and must not directly trigger code delivery or shipment. Even with a platform order number, wait for a trusted successful payment result. Technical staff provide complete error code handling and response verification details during integration testing.
Order query: GET the original order
Example URL: https://gateway.example.com/api/pay/collect/query; method: GET. Sign the actual query parameters first, then construct the query string with standard URL encoding.
| Field | Required | Value requirements |
|---|---|---|
mchId | Yes | The merchant number associated with the order. |
outTradeNo | One of the two | Merchant order number; choose this or platform_order_no . |
platform_order_no | One of the two | Platform order number; note the underscore-separated parameter name. |
reqTime | Yes | Current millisecond timestamp for this query. |
sign | Yes | Generate a new signature from these query parameters; do not reuse the order creation signature. |
The query response data example contains platformOrderNo、merchantOrderNo、amount、currencyCode、orderStatus、payUrl. The request parameter platform_order_no and the response field platformOrderNo are spelled differently; do not reuse the same parameter object directly.
The query response amount units and precision must be confirmed with technical staff during onboarding. Explicitly convert to your internal amount convention before comparing; do not directly compare this value with the order request amount in fen.
Order states and corresponding business actions
| orderStatus | Meaning | Application action |
|---|---|---|
0 | Pending payment | Show that payment is pending and query on schedule; do not fulfill. |
1 | Payment successful | After checking the trusted result, enter idempotent fulfillment. |
2 | Payment failed | Record the failure; handle the original order according to the agreed rules before accepting another payment attempt. |
3 | Closed | Stop waiting, but retain the order and verification records. |
4 | Expired | Show the expired state and follow the agreed rules for repurchasing and unexpected receipts. |
An HTTP timeout is not an order state. Record the result as awaiting confirmation and query the original merchant order number. Until the result is confirmed, do not assume that the original request failed or bypass duplicate checks by assigning a new number.
Use the same payment handling function for callbacks and queries
- Locate the original orderRead the local record by merchant number and merchant order number, then confirm the associated customer and environment.
- Check the trusted resultVerify callbacks before processing them. Make queries through protected backend requests and verify the response according to the integration specification.
- Apply one idempotent update workflowPersist the successful state only once and give the fulfillment task a unique business key.
- Record inconsistenciesStop fulfillment when the amount, currency or state does not match, and ask technical staff to help verify the result.
Continue reading: signing rules and callback handling details. This article is based on the 稳付pay integration specification.
Confirm integration for your business scenario
Describe your products, order volume, payment methods and settlement needs to confirm the APIs, movement of funds and exception handling item by item.
Contact 稳付pay ↗