​

Payment states

A payment has one current status. Treat webhook events as notifications to refresh your local view, not as permission to skip your own order, amount, and currency checks.

​

Transitions

​

Safe fulfilment rule

Only paid permits fulfilment. Even then, compare all of the following against your locally persisted order:

• payment_id
• external_reference
• Requested currency, decimal amount, and minor_units
• Payment-instruction asset, network, destination, decimal amount, and sun
• The event_id already processed by your webhook consumer

Make fulfilment idempotent. A repeated retrieval, webhook delivery, or worker run must not produce a second ledger entry, entitlement, shipment, or receipt.

​

Handling submission_unknown

An unknown outcome is not success and is not a reason to create another payment. Retain the original external_reference and Idempotency-Key, mark the local order for recovery, and wait for an authoritative response or state update. Stage Sandbox recovery window for unresolved submission_unknown is 15 minutes (900 seconds). Without previously persisted accepted authority, recovered provider data cannot authorize automatic pending, cancelled, or paid. A unique recovered identity or an expired unresolved window moves the payment to review_required. Provider resubmission is forbidden.