Idempotency
For create requests, the platform treats the same merchant and merchantOrderNo as one logical business order. Generate and save the merchant order number before sending the request. It must be unique under the same merchant number and reused for order query, reconciliation, Webhook correlation and recovery after an uncertain create result.
| Scenario | Platform behavior | Merchant action |
|---|---|---|
First create request with a merchantOrderNo | Create the order and return the platform order number and current status | Save merchantOrderNo, platOrderNo and the order status; use status, query API or Webhook for the business result |
Same merchant, same merchantOrderNo and same business parameters | Do not create another order; return the current status and original platform order number of the first accepted order | Treat it as a status read for the same order; do not duplicate ledger, fulfillment, refund or payout handling |
Same merchant and same merchantOrderNo, but different business parameters | Return HTTP 409 with MERCHANT_ORDER_NO_CONFLICT | Stop retrying and check whether the order number was reused by mistake; use a new merchantOrderNo only for a new real business order |
If a create result is not confirmed, do not place another order with a different merchant order number. This is especially important for payouts, because the first request may already have entered debit or disbursement processing.
If a user makes three separate top-ups of 100, create three different merchant order numbers, such as PAY_001, PAY_002 and PAY_003. The same amount, goods or recipient does not make them the same order. Reuse the original merchantOrderNo only when recovering the same business order after a timeout, connection loss or unverifiable response.
An idempotent duplicate does not update an existing order. The response keeps the business fields and customData saved from the first accepted create request; fields from a later request are never merged into or used to overwrite that saved data.
Do not automatically or concurrently retry a business create request. Configure the HTTP client so each create request is initiated explicitly by the business system. If a retry is needed, query first and keep the same order identity and business fields.