A payment provider's event name should remain visible after it changes an order. Store the original event, the rule that interpreted it and the resulting business decision. This gives an operator a way to explain an order state when two providers use different terminology.
This is an adapter and ledger design for the unimplemented Stablecoin Payment Operations blueprint. It covers proposed state mapping, with no live provider connection or executed integration tests. The accompanying worksheet keeps every proposed case marked Not run.
Preserve provider identity before mapping
Save the provider account, environment, event identifier, event type and referenced payment object. Keep receipt time separate from the event's own timestamp. Associate the raw event with a mapping revision so a later rule change does not silently rewrite the explanation for an earlier decision.
Stripe documents duplicate webhook deliveries and does not guarantee delivery order. Its guidance also describes retrieving related objects when needed. An adapter must therefore cope with repeated or late evidence instead of assuming the arrival sequence is the payment sequence. Stripe webhooks.
Choose a retention policy for raw payloads before collecting them. Store enough evidence to investigate a payment without indiscriminately copying customer data into every log. An operator-facing event view can show references and mapping decisions while restricting access to the original payload.
Map facts into business decisions
Define order states in terms the business can act on. For this proposed model, pending means authoritative payment confirmation is incomplete. Paid requires the selected confirmation rule and an order match. Review means evidence cannot be safely mapped. Refund progress belongs in its own record so a partial refund does not erase the history of the original payment.
Stripe's PaymentIntent object exposes distinct states including processing, requires_action and succeeded. Its fields also include currency and received amount. These distinctions illustrate why a generic event called updated cannot establish that an order is paid. PaymentIntent object.
| Incoming evidence | Proposed handling | Order effect |
|---|---|---|
| Known pending status | Save reference and wait | Remain pending |
| Confirmed payment matching the order | Record the accepted payment fact | Permit the defined paid transition |
| Repeated event identifier | Preserve receipt evidence without repeating effects | Keep current state |
| Unknown status or schema | Route to exception review | Do not infer payment |
| Refund update | Update the referenced refund record | Recalculate the explicit refund view |
Validate the match before fulfillment
A valid webhook signature establishes the expected sender under the provider's verification scheme. The integration still needs to compare the referenced payment with the correct order, account and environment. A test-mode event must not fulfill a production order merely because its payload uses a recognizable identifier format.
For token transfers, keep the chain and contract identity alongside the amount. ERC-20 defines the Transfer event and permits zero-value transfers. A transfer event by itself therefore says less than the business statement that the expected order amount has been received. ERC-20 transfer events.
Record failed comparisons as evidence rather than discarding them. A wrong-currency payment reference or an unknown order identifier needs an exception owner. Keep the order pending or under review according to the agreed policy while the operator investigates.
For the delivery retry path that follows an accepted order decision, see the separate payment webhook recovery guide. Keep its fulfillment operation distinct from the provider-event mapping described here.
Handle late events and refunds deliberately
Do not let a late pending event overwrite an already accepted payment fact. Use explicit transition rules and retain the conflicting evidence for inspection. When the event stream is insufficient, query the provider's authoritative object through the adapter and record that reconciliation result as another observation.
Stripe documents partial refunds and refund lifecycle events, including failures. A refund request being accepted is therefore a different fact from the refund reaching its successful final state. Model those facts separately and apply the chosen provider's status semantics. Refund handling.
Test proposed mappings against a repeated notification, an unknown status and an older event arriving after confirmation. Include an event with the right order reference but the wrong environment. A useful result record shows the original event, mapping revision and allowed side effect for each case.
Download the payment event mapping worksheet to fill in those rules for a selected provider. The template includes blank reconciliation evidence and a place to explain unmapped events; it is not an adapter implementation.
Review the Stablecoin Payment Operations blueprint to scope a provider test environment, an order ledger and exception review. Bring the current order states and real provider documentation before extending the mapping to another channel.
