Transaction Status Model

Transaction states describe fund-movement progress. A wallet displays deposit pending, withdrawal processing, or completion; transfers and payments advance business workflows according to the fund movement's result. API success, record creation, and financial completion are different decisions.

HTTP responses and financial results

Observation	What it establishes	What to check next
HTTP success and success: true	The API request succeeded	The returned transaction's state
deposit_id or withdrawal_id	A transaction exists to retrieve/track	Its completion conditions
Non-final state	Processing is still in progress	Later detail for the same transaction
Transaction-specific success conditions	Financial success can update your workflow	Related amounts and ledger consistency

For example, successful withdrawal creation returns a withdrawal_id while the withdrawal can still be processing. A successful deposit detail request does not confirm successful funding unless that deposit has status: COMPLETED.

Deposit and withdrawal state fields

Resource	State fields	Interpretation
External deposit	status	Detailed confirmation, approval, and refund state
Internal deposit	status	Displays PENDING or COMPLETED
External withdrawal/internal transfer	status, user_status	Detailed processing state and customer display state

Withdrawal status and user_status use different value sets. Detailed states include REQUESTED, HOT_STAGE, and HOT_FAILED; customer states include PENDING, PROCESSING, and FAILED. Do not compare the two as the same enum or assume deposit responses contain user_status.

Customer wallet withdrawal behavior

user_status	Meaning	Display and workflow behavior
PENDING	Accepted and waiting	Display pending and continue detail polling
PROCESSING	Processing	Display progress and prevent duplicate withdrawals
COMPLETED	Complete	Verify success conditions and transaction data, then display completion
FAILED	Failed	Verify the failure and balance recovery
REJECTED	Rejected	Check the reason and close the workflow
CANCELLED	Cancelled	Confirm cancellation and the balance

External withdrawals require status: COMPLETED, user_status: COMPLETED, and a valid tx_hash. A hash during processing does not establish completion. Internal transfers require request_type: INTERNAL and both completed states without an on-chain hash.

For a long-running withdrawal, keep its request and transaction IDs and continue tracking. Delay is not grounds for another withdrawal. See Withdrawal Flow.

Deposit behavior

External deposit processing states include PENDING, INSPECTED, APPROVE_PENDING, APPROVED, and VERIFIED. Apply successful receipt only at COMPLETED.

REFUND_REQUIRED, REFUND_REQUESTED, and REFUND_PENDING describe required or ongoing refunds. REFUNDED and FAILED are unsuccessful final deposit outcomes. Your interface can distinguish processing, refund progress, and failure while retaining the original state values.

Status Codes lists the values, and Deposit Flow explains wallet credit and queries.

Discovery and later state changes

Cursor lists discover new transactions; detail queries update already discovered transactions.

First list: discover deposit 200, status=PENDING, save cursor=200
  → later lists discover new deposits after 200
  → separate detail queries confirm deposit 200 is COMPLETED

When deposit 200 completes, its ID does not reappear in the cursor feed. Separate discovery from non-final detail polling to avoid missing wallet completions. The same principle applies to withdrawals.

Persist final results and remove finalized transactions from normal status tracking. The ledger appends finalized movements, so use its cursor to discover new entries. Discovery order and financial completion time are different concepts.

When to update business state

Workflow	Completion rule
Customer wallet funding	External deposit status: COMPLETED
Customer external withdrawal	Both external completed states and a valid tx_hash
Account transfer	Internal transfer type and both completed states
Order payment	Completion of the internal transfer linked to that order
Merchant external settlement	Completion of the external withdrawal linked to that settlement

Apply completion notifications and order updates idempotently so repeating the same response has one business effect. Balance changes are supporting checks, not replacements for individual transaction state.

Persistence and recovery

Store transaction type/ID, your business ID, original status, withdrawal user_status, last-check time, next-check time, and final flag. Resume polling stored non-final transactions after a restart.

Do not compare state strings alphabetically or numeric codes by magnitude to infer progress. If a later response contradicts a stored final result or contains an unknown state, retain the original data and stop automatic business updates pending investigation. See Error Handling and Retry for HTTP retries and Incremental Synchronization for discovery/status tracking.