Payment Checkout & Ledger Service  ·  View 05 of 24  ·  People and journeys

Journey — The Merchant Developer Integrates

The journey whose trough is a duplicate webhook that ships the goods twice.

Editable source SVG draw.io All views
Merchant developer one afternoon, no payments background Goal — A working checkout that does not double-ship goods Trigger — A ticket saying 'add payments to the new storefront' Done when — Orders marked paid exactly once, from events, with no polling cron 1 · Read and key credentials 2 · First payment sandbox 3 · Receive events ◆ moment of truth 4 · Handle the unhappy path ◆ moment of truth 5 · Go live production keys What they do Gets test keys Creates an intent Confirms it client-side Writes a webhook handler Simulates a decline Replays an event Swaps the key What the platform gives Publishable + secret key Intent API Client secret Signed webhook Per-object sequence Sandbox failure modes Replay API Same contract, real rails How it feels In control Fine Lost Where it hurts Duplicate webhook ships twice Events arrive out of order No way to test unknown What answers it Scoped, revocable keys Intent, not a raw charge Sequence number per object At-least-once, stated Injectable unknown outcome No code change to go live Journey — The Merchant Developer Integrates The platform promises at-least-once delivery and says so. The sequence number is what lets a naive handler be correct anyway. v 1.0 · owner Payments Platform Architecture · date 2026-10

The trough

  • 'Receive events' is the worst moment, and the failure is not in the platform: it is a merchant handler that is not idempotent.
  • The platform's answer is to promise at-least-once explicitly and give a per-object sequence number, so a naive handler can detect a gap and a duplicate without understanding payments (ADR-09).

Decisions

  • Publishable and secret credentials are separate, and a publishable credential can do nothing but confirm an existing intent (ADR-15).
  • The sandbox can inject the unknown outcome. If a failure mode cannot be tested, every merchant discovers it in production.
  • Going live is a credential swap, not a code change.

Risks

  • Ordered-per-object delivery would be kinder to naive handlers and introduces head-of-line blocking that one slow endpoint turns into everyone's backlog. The trade is left open as Question 6 and decided in ADR-09.
◀  Journey — The Buyer Pays All views Journey — Finance Ops Closes the Day  ▶
Solution Architecture v1.0 · open source, self-hosted on Kubernetes across two in-country data centres · Payments Platform Architecture · 2026-10 · 24 views · 18 architecture decision records05-journey-merchant-integrates