Skip to main content

Payments Architecture

Router Flow​

All production payment flows settle through:

Client -> X402FlexRouter -> X402FlexRegistry

This guarantees one canonical settlement event shape across push, pull, relay, and session flows.

Canonical settlement event​

PaymentSettledV2 is the source of truth for reconciliation.

Key fields:

  • paymentId
  • resourceId
  • referenceData
  • referenceHash
  • schemeId
  • amount and feeAmount

Use decodePaymentSettledEvent for consistent decoding in indexers/services.

Deterministic identity model​

What this does: binds payment identity to immutable intent terms.

paymentId is derived from:

  • token
  • amount
  • deadline
  • resourceId
  • referenceHash
  • nonce

Expected result: if these fields are unchanged, paymentId is unchanged.

Common failure mode:

  • If final referenceData changes but referenceHash is not recomputed, settlement verification breaks.

SDK architecture mapping​

  • Intent creation: createFlexIntent
  • Execution: sendRouterPayment, payWithPermit2, payWithEIP2612, payWithEIP3009
  • Verification: decodePaymentSettledEvent or api.payments.get(paymentId)

What this means for integrators​

  • Persist nonce for every intent.
  • Persist both paymentId and resourceId for query + analytics joins.
  • Treat referenceData as a first-class business key (invoice ID, agent task ID, etc.).

Common errors and fixes​

  • Wrong chain/router pair: enforce per-network config validation.
  • Missing confirmations in verification path: wait for target confirmation depth.
  • Session flow mismatch: use session-tagged references and current session auth values.