Collection APIs

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.

FieldRequiredValue requirements
mchIdYesYour merchant number; the example uses a string.
wayCodeYesAn enabled channel or aggregate code; the example uses a string.
outTradeNoYesMerchant order number, unique within the merchant account and associated with the local order.
amountYesOrder amount in fen; the integer 1000 represents 10.00 yuan.
currencyCodeNoCurrency; the default is CNY。
notifyUrlYesYour asynchronous notification URL, for example https://merchant.example.com/pay/notify。
subjectNoProduct title; include it in signing if submitted.
bodyNoProduct description; include it in signing if submitted.
clientIpNoClient IP, supplied according to the actual scenario.
reqTimeYesCurrent millisecond timestamp; the example uses an integer.
signYesLowercase 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.

JSON field example
{
  "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"
}
Python backend request construction
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 transport example
curl --request POST "$API_BASE_URL/api/pay/collect/create" \
  --header "Content-Type: application/json; charset=UTF-8" \
  --data @collect-create.json

Download 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

Python GET parameters
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.

FieldRequiredValue requirements
mchIdYesThe merchant number associated with the order.
outTradeNoOne of the twoMerchant order number; choose this or platform_order_no .
platform_order_noOne of the twoPlatform order number; note the underscore-separated parameter name.
reqTimeYesCurrent millisecond timestamp for this query.
signYesGenerate 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

orderStatusMeaningApplication action
0Pending paymentShow that payment is pending and query on schedule; do not fulfill.
1Payment successfulAfter checking the trusted result, enter idempotent fulfillment.
2Payment failedRecord the failure; handle the original order according to the agreed rules before accepting another payment attempt.
3ClosedStop waiting, but retain the order and verification records.
4ExpiredShow 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

  1. Locate the original orderRead the local record by merchant number and merchant order number, then confirm the associated customer and environment.
  2. Check the trusted resultVerify callbacks before processing them. Make queries through protected backend requests and verify the response according to the integration specification.
  3. Apply one idempotent update workflowPersist the successful state only once and give the fulfillment task a unique business key.
  4. 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 ↗