​

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. The payment resource is the read model. Event names do not create a second, competing lifecycle.

​

Proposed transitions

This transition diagram is normative only for reviewing the draft. The final implementation must be tested before the lifecycle can become a public guarantee.

​

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 minimum-unit amount
• Payment-instruction asset, network, destination, and exact amount
• 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. Because this preview does not represent a deployed implementation, it does not promise a recovery duration. Merchant timeout and customer messaging policies must remain conservative until the operational contract is approved.