Which signal should be allowed to authorise fulfilment?
Fulfilment should follow an authenticated server-to-server payment event whose status, amount, currency and provider reference match an internal order and payment attempt. A browser success page, client response, email or screenshot can inform the customer, but it should not authorise shipping, access or a booking because it is incomplete, interruptible or easier to imitate.
Separate customer navigation from payment evidence
A customer can close the browser before returning, reload a page or reach a redirect without the internal workflow completing. Payment providers therefore recommend receiving server-side events rather than relying on the success page alone. The return page can show a useful pending state while the backend verifies and applies the provider's evidence.
Authenticate before interpreting
Verify the provider's event signature or equivalent authentication using the raw message and the documented method. Reject stale, malformed or unauthenticated events before they influence business state. Network origin, a plausible payload or knowledge of an order identifier is not proof that the provider sent the event.
What must the internal transaction record know?
Keep an internal order, one or more payment attempts, the expected amount and currency, provider references, current states and a history of applied events. The provider reports what happened in its system; the business record decides what that evidence means for this order. Do not use a mutable cart, browser session or email address as the durable join between them.
Create the relationship before sending the customer away
Persist the order or reservation and payment-attempt identifier before opening the hosted payment experience. Include only a safe internal reference in provider metadata where supported. When an event arrives, resolve it through the stored provider reference and verify the expected commercial facts rather than accepting identifiers or values from the client.
Model payment and fulfilment separately
Paid, refundable, disputed and refunded describe payment. Reserved, released, dispatched and completed describe fulfilment. Keeping those lifecycles separate lets the product express a paid order awaiting stock, a refund after dispatch or a payment that arrived after a reservation expired. One broad status field usually hides these necessary decisions.
How should duplicate, delayed or out-of-order events behave?
Event processing should be idempotent: applying the same evidence more than once must not create another shipment, licence or booking. Record provider event identifiers and protect the fulfilment transition with a unique business key or atomic state change. Events may be retried or arrive out of sequence, so handlers should evaluate current state instead of assuming a perfect timeline.
Acknowledge delivery separately from completing work
Validate and durably record the event quickly, then process slow fulfilment through a controlled job where appropriate. A successful response to the provider should mean the event will not be lost, not necessarily that every downstream step finished synchronously. Failed jobs need visible retry state, ownership and a safe limit.
Protect the irreversible transition
Before releasing value, atomically claim the right to fulfil the order. If two workers handle equivalent evidence, only one should move the order into the fulfilment path. Downstream operations also need their own idempotency or reconciliation because a process can fail after an external carrier, email service or entitlement system accepts a request.
What should happen when the provider and product disagree?
Treat disagreement as a visible state requiring reconciliation, not as permission to guess. Query authoritative provider state where supported, compare it with the event history and internal records, then apply a defined recovery rule. Keep fulfilment on hold when material facts conflict, and give an operator enough context to resolve the case without editing database fields blindly.
Run reconciliation independently of webhooks
Events can be delayed, endpoints can be unavailable and internal processing can fail after receipt. A scheduled reconciliation process should find ageing pending attempts, provider payments without completed internal transitions and orders whose commercial totals disagree. This secondary path turns a silent mismatch into a work item before a customer discovers it.
Define recovery by consequence
A low-value digital entitlement may tolerate automatic retry after verification. A high-value physical dispatch may require review when the amount, currency or order version differs. Record who may release a hold, what evidence they inspect and how the action is audited. Recovery policy is part of the product, not an informal support procedure.
What should the team prove before going live?
Test successful, failed, delayed, abandoned, duplicate, reordered, refunded and disputed payment paths against realistic order states. Confirm that unauthenticated or mismatched evidence cannot release value, retries do not duplicate fulfilment and reconciliation finds missed transitions. The launch case should also identify alerts, operator ownership, provider-dashboard access and a controlled way to pause fulfilment.
Test the gaps between systems
Interrupt the workflow after provider acceptance but before the internal update, and after the internal transition but before a downstream operation confirms. Replay the same event and send a valid event for the wrong amount. Inspect the provider, internal history and downstream system after each case; a friendly screen is not evidence that the state is correct.
Start with the authority chain
Twofold's transaction and commerce work can help map the order, payment and fulfilment lifecycles before implementation. Bring the provider flow, the value being released and the current recovery process. The first useful output is an explicit authority chain: which evidence is trusted, how it is matched and which guarded transition it may trigger.