Chapter 07 - Payment orchestration
v1 shipped - deploy gated
A Go/PostgreSQL payment orchestration service that drives authorize-to-capture intents through SimPSP failures, leases stuck work, and books terminal money movements into Arus exactly once.
Source: orchestration/backend origin/main e34c23d; PR #3 fixup b74828a; M3 walkthrough records race verification and chaos gate evidenceArus records money, WebhookOps delivers operational events, Family Finance consumes the API, Selaras assures settlement, and Alur orchestrates the payment state machine in front of an unreliable PSP.
Source: orchestration/docs/product-requirements/2026-06-12-v01-orchestration-v1-prd.mdThe canonical question is what happens when the PSP charges but the response times out. Alur keeps the attempt record, lets the reaper poll PSP truth, and completes without a second charge.
Source: orchestration/docs/system-analysis/2026-06-12-v01-orchestration-v1-sa.mdState machine
Worker claims due work with `FOR UPDATE SKIP LOCKED`, records the PSP attempt, commits, then calls SimPSP with the persisted idempotency key.
Source: orchestration/docs/system-analysis/2026-06-12-v01-orchestration-v1-sa.mdAuto-capture is v1's only capture mode; terminal capture success enqueues the Arus booking outbox row in the same transaction.
Source: orchestration/backend/internal/domain/transition.goPast-deadline in-flight work is leased by extending `state_deadline`, then resolved through SimPSP status truth instead of webhook optimism.
Source: orchestration/backend/internal/worker/worker.goRefunds use the same attempt discipline, with the review-fix path leasing `processing` retries before any PSP send.
Source: orchestration/backend/internal/httpapi/m3_acceptance_test.goThree-layer idempotency
Merchant calls carry `Idempotency-Key`; same request replays return the original intent or refund, while different bodies conflict through request hashes.
Source: orchestration/docs/adr/2026-06-12-v01-adr-002-three-layer-idempotency.mdEvery outbound authorize, capture, or refund attempt gets a fresh PSP idempotency key recorded before send, so recovery can replay without blind double effects.
Source: orchestration/docs/system-analysis/2026-06-12-v01-orchestration-v1-sa.mdThe outbox external ref is unique and the drainer treats Arus existing-entry replay as success, preserving exactly-once booking semantics across retries.
Source: orchestration/backend/internal/worker/outbox.goADR callouts
The portfolio value is in visible payment mechanics, so v1 uses PostgreSQL legal transitions, append-only logs, and outbox rows rather than hiding recovery inside a workflow engine.
Source: orchestration/docs/adr/2026-06-12-v01-adr-001-hand-rolled-state-machine.mdAPI retries, PSP retries, and Arus post retries each own their own idempotency key or external ref because any layer can fail after a previous layer succeeded.
Source: orchestration/docs/adr/2026-06-12-v01-adr-002-three-layer-idempotency.mdWebhooks are a fast path. The reaper's PSP status poll is the mandatory correctness path for stuck in-flight intents and timeout-after-charge recovery.
Source: orchestration/docs/adr/2026-06-12-v01-adr-003-webhooks-plus-polling.mdChaos PSP gate
The gate creates 500 intents and assigns `ok`, `decline_hard`, `fail_5xx_then_ok:2`, `timeout_after_charge`, `timeout_before`, `webhook_dup:3`, and `webhook_ooo` round-robin.
Source: orchestration/backend/internal/httpapi/m3_acceptance_test.goThe test repeatedly runs worker and reaper with forced deadline expiry, then fails unless zero non-terminal intents remain.
Source: orchestration/backend/internal/httpapi/m3_acceptance_test.goFor every created intent, the SimPSP charge ledger must show at most one charge after the storm.
Source: orchestration/backend/internal/httpapi/m3_acceptance_test.goFor every successful capture, the test requires one booking row, one fake-Arus post, and zero pending/failed outbox rows after drain.
Source: orchestration/backend/internal/httpapi/m3_acceptance_test.goLoop closing
Alur posts balanced entries through the Arus API and never configures an Arus database connection.
Source: orchestration/docs/security/2026-06-12-v01-alur-m3-threat-model.md`alur:<intent>:capture:v1` and `alur:<intent>:refund:<refund>:v1` are stable references that Selaras can reconcile against SimPSP settlement exports.
Source: orchestration/docs/system-analysis/2026-06-12-v01-orchestration-v1-sa.mdThe drainer marks rows posted when Arus reports the external ref already exists, so outbox retries close cleanly instead of creating duplicates.
Source: orchestration/backend/internal/worker/outbox.goHonesty line
Roadmap
The current service ships auto-capture only; explicit authorize-then-capture control is a named v2 workflow extension.
Source: orchestration/docs/product-requirements/2026-06-12-v01-orchestration-v1-prd.mdv1 is IDR-only with one SimPSP adapter. Multi-currency, FX, processor routing, and failover are intentionally deferred.
Source: orchestration/docs/product-requirements/2026-06-12-v01-orchestration-v1-prd.mdSimPSP proves orchestration failure classes, while processor-specific auth and production certification stay outside v1.
Source: orchestration/docs/security/2026-06-12-v01-alur-m3-threat-model.mdThe prepare script exits before cloud mutation and prints `no cloud command executed`; live deployment requires a separate human gate.
Source: orchestration/backend/scripts/prepare-cloud-run.shPlatform links
Alur books terminal money states into Arus through the API and inherits its external-ref replay contract.
Source: orchestration/docs/system-analysis/2026-06-12-v01-orchestration-v1-sa.mdAlur external refs are shaped so Selaras can reconcile SimPSP settlement exports against Arus postings.
Source: orchestration/docs/system-analysis/2026-06-12-v01-orchestration-v1-sa.mdEvidence trail