Order Lifecycle

Global Account › Guides

15 order states, terminal outcomes, and where funds sit at each stage. Alert on unknown states; never silently substitute another.


pending ─► reviewing ─┬─► dispatching ─► submitting ─► processing ─┬─► completed
   │          │       │                                            ├─► failed
   │          │       └─► dispatch_failed                          └─► refunded
   │          ├─► supplementing ┐
   │          ├─► needs_reconfirm ├─► 回到主线
   │          └─► rejected        │
   └─► canceled            pending_docs ─► docs_submitted ┘

All Values

In progress — The order can still change; continue tracking:

Value	Meaning	Where the member's funds are
`pending`	Accepted and queued	Unchanged
`platform_reviewing`	Our platform risk review	Locked
`reviewing`	Under review	Locked
`supplementing`	Additional information requested during our review	Locked
`needs_reconfirm`	Price movement exceeded slippage; awaiting member reconfirmation	Locked
`dispatching`	Dispatching upstream	Locked
`dispatch_failed`	Dispatch failed; awaiting our manual action	Locked
`submitting`	Submitted upstream	Locked
`processing`	Processing upstream	Locked
`pending_docs`	Upstream RFI; funds are at the partner bank and more information is required	Locked
`docs_submitted`	Information submitted; awaiting upstream review	Locked

Terminal — No further changes:

Value	Meaning	Where the member's funds are
`completed`	Paid to the payee	Paid out
`failed`	Failed	Returned to available balance
`refunded`	Refunded	Returned to available balance
`rejected`	Rejected	Returned to available balance
`canceled`	Canceled	Returned to available balance

⚠ pending is the only in-progress state in which no funds have moved. It is the queue

before freezing. Do not show Funds frozen for this state.

In every other in-progress state, the member's funds remain locked.

⚠ dispatch_failed is not a terminal failure. Funds remain locked pending our manual action.

Showing it as failed makes users expect a refund and then question why their balance has not changed.

Three Required Rules

1. `completed` Does Not Merely Mean Upstream Reported Completion

After the upstream completion signal, we still post settlement. The event and order status become completed only after settlement.

2. Alert on Unknown States; Do Not Use a Fallback


switch (status) {
  case "completed": …
  case "failed":    …
  …
  default: alert(status);   // ← 不是 fallthrough 到「处理中」
}

Defaulting to Processing can leave a new terminal state displayed as processing forever while users never see the outcome and your monitoring stays silent.

We follow the same rule ourselves: apart from the pending mapping, unrecognized statuses are returned unchanged, never replaced with a default. New enum values are recorded in the changelog before introduction.

3. Merge by `status_version`

Events and polling responses can arrive concurrently and out of order. Only move forward:


if (incoming.status_version > local.status_version) apply(incoming)

Deciding Whether to Continue Tracking

Use the 5 terminal states as your condition, rather than enumerating in-progress states:


const DONE = new Set(["completed", "failed", "refunded", "rejected", "canceled"]);
if (!DONE.has(order.status)) keepPolling(order);

We may add in-progress states; platform_reviewing and pending were both added later. An explicit in-progress list that omits a new state causes the order to silently disappear from your tracking queue.