Payment Checkout & Ledger Service  ·  View 17 of 24  ·  Runtime

Merchant Notification by Event Class

Five lanes across emit, sign, attempt, retry and catch up — and what happens when an endpoint is simply down.

Editable source SVG draw.io All views
Emit Sign and queue Attempt Retry Catch up Payment outcome payment.succeeded HMAC + seq n POST, 5 s budget backoff to 72 h replay by id Refund and dispute refund.updated same signature POST backoff to 72 h list since cursor Payout and balance payout.paid batched per merchant POST daily digest fallback statement download Ordering guarantee per-object seq no global order gap detectable no head-of-line block cursor is authoritative Failing endpoint events still emitted per-merchant queue 5xx / timeout isolated, not shared auto-disable + notice Merchant Notification — Delivery by Event Class At-least-once, stated in the contract. One stalled merchant endpoint never delays another merchant's events — the queue is per merchant. v 1.0 · owner Payments Platform Architecture · date 2026-10

Decisions

  • At-least-once delivery, stated in the contract rather than implied. The platform does not claim exactly-once it cannot provide (ADR-09).
  • A per-object monotonic sequence number is the ordering guarantee: a merchant can detect a gap without a global order existing.
  • Each merchant has its own delivery queue, so a stalled endpoint delays nobody else's events — the explicit rejection of ordered-per-object delivery and its head-of-line blocking.

Numbers

  • Dispatched within 5 s of the state change for 99.9% of events; retried with backoff for up to 72 hours.
  • Then a pull-based event list with a cursor, so a merchant down for a week catches up without a support ticket.
  • Stated assumptions.

Risks

  • Auto-disabling a persistently failing endpoint is the right operational act and will occasionally silence a merchant who was about to come back. The notice path matters as much as the disable.
◀  Settlement and Payout Pipeline All views Deployment — Two In-Country Data Centres  ▶
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 records17-webhook-delivery-lanes