Guide
Merchant integration architecture
Layered server-side boundaries for B2B crypto payments—API authority, webhook verification, lifecycle mapping, reconciliation, and treasury controls.
Definitions: Payment rail abstraction · Selected rails · Merchant approval
Conceptual operational diagram for this guide. Not live merchant data or metrics.
01
Reference layers
- Commerce layer — creates payable intent with stable references.
- API layer — server-side payment creation and reads; secrets never in browsers.
- Webhook layer — raw-body verification, idempotency, replay controls.
- Lifecycle layer — explicit state transitions and checkpoints.
- Reconciliation layer — three-plane matchers and exception queues.
- Treasury layer — recognition and payout orchestration under finance policy.
02
Trust boundaries
Verification middleware is narrow: authenticate callbacks before application logic. Business rules (fulfillment, entitlements, posting) live in services finance can audit. Rail abstraction exposes stable semantics while detection rules remain configuration-bound per environment.
03
Environment separation
Separate API keys, webhook secrets, and matcher tolerances per environment. Staging should replay fixtures with known signatures—never production secrets in demos.
Read: Server-side API keys, Integration docs, Production infrastructure.
- Retries are normal. Webhook delivery is at-least-once. Design consumers to tolerate duplicates and out-of-order arrivals where possible.
- Asynchronous by design. Payers, chains, and your servers operate on different clocks. UI and finance should not assume synchronous finality.
- Eventual consistency. API reads, webhooks, and portal views may briefly diverge during transitions. Reconciliation jobs exist to converge truth.
Walkthroughs: /operations