Payments Hub Architecture
Understand how Payments Hub coordinates clients, Ledger, wallets, intents, proofs, bridges, external rails, and webhooks when money moves.
Payments Hub is the payment orchestration layer built on Minka Ledger. Client applications describe what should happen, Ledger validates and records it, and bridges connect the ledger workflow to bank cores, directories, QR networks, card rails, or real-time payment systems.
The important idea is separation of responsibility: Ledger is the source of truth for records, proofs, balances, and payment state. Bridges are responsible for external side effects such as reserving funds, debiting an account, crediting an account, synchronizing an alias, or delivering a notification to a participant system.
Use this page when you need the full mental model before implementing merchant onboarding, payment sending, anchor-based collection, or webhook subscriptions.
Client-facing terms
| Term | What it means for an integration team |
|---|---|
| Client application | Your channel, backend, merchant system, participant system, or operations tool that calls Ledger APIs. |
| Ledger | The canonical payment coordination system. It stores wallets, anchors, intents, effects, policies, balances, proofs, and history. |
| Wallet | A Ledger account address that can hold or route balances. A wallet may represent a bank account, merchant account, settlement wallet, treasury account, or network account. |
| Anchor | A discoverable payment reference such as an alias, account identifier, QR payment point, or one-time checkout reference. |
| Intent | The payment instruction. It contains one or more claims that say what value should move, from where, to where, and under which symbol. |
| Claim | A structured instruction inside an intent, usually a transfer, issue, destroy, or limit action. |
| Proof | Signed evidence that a party authorized, validated, prepared, committed, failed, or otherwise attested to a record or lifecycle step. |
| Bridge | A participant or rail integration service called by Ledger when a payment requires work outside the ledger. |
| Effect | A Ledger subscription that delivers webhooks or bridge callbacks when matching events happen. |
Documentation gaps this page fills
The Moving Money guides already explain how to run individual tasks. The missing layer is the end-to-end map that shows how those tasks relate during a production payment.
This page adds that map:
| Gap | Why clients need it | Where this page covers it |
|---|---|---|
| No single Payments Hub overview inside Moving Money | Integration teams need to know where their system, Ledger, bridges, and rails sit before choosing an API path. | System context and Container view |
| Intent lifecycle is spread across how-to guides | Teams need to understand that payment state changes through proofs, not by directly editing a completed intent. | Intent lifecycle and Payment initiation and execution |
| Proofs are mentioned as security detail but not shown as operational evidence | Teams need to know which party signs what and how bridge outcomes become auditable payment state. | Proof generation and validation |
| Wallets, anchors, QR, and accounts can feel like separate features | Teams need to see that anchors resolve to wallets and intents move balances between wallets. | Wallet and account interaction |
| Webhooks are documented as setup, not as part of the payment lifecycle | Teams need to treat notifications as asynchronous delivery, not as the source of truth. | Webhook delivery |
| Error and reversal behavior is not visible in one place | Teams need deterministic handling for rejections, aborts, retries, and post-settlement compensation. | Rejected payments and reversals |
Recommended diagram set
| Diagram | Include? | Rationale |
|---|---|---|
| C4 System Context | Yes | Best first view for client teams: who calls Payments Hub, what is external, and where Ledger and bridges fit. |
| C4 Container | Yes | Shows the practical integration boundaries: Ledger API, policy/schema validation, DTC processing, effects, bridges, and external systems. |
| C4 Component | No for this page | Component-level internals add noise for most client onboarding. Link to API and bridge docs instead when implementation details are needed. |
| C4 Deployment | No for this page | Deployment varies by client environment. It is useful for project onboarding, but not for explaining the public integration model. |
| Sequence diagrams | Yes | Sequence diagrams explain what happens over time: intent creation, bridge prepare/commit, proof submission, webhooks, and failure handling. |
System context
From a client perspective, Payments Hub is not a separate payment database. The integration surface is Ledger plus the configured bridge behavior behind it. You create and query Ledger records; the hub coordinates the external participants required to make those records true in connected systems.
Container view
The Ledger API is the client-facing boundary. Bridge calls are normally behind the hub boundary and are operated by Minka, a participant, or a rail-specific integration team. If your organization operates a bridge, see About Bridges, Build a Banking Core Bridge, and Bridge Error Handling.
What happens before a payment
A production payment usually depends on setup records that already exist:
| Setup record | Purpose | Related guide |
|---|---|---|
| Signer | Identifies who can create wallets, anchors, effects, and intents. | About Signers |
| Wallet | Represents the source, target, merchant, settlement, treasury, or participant account. | About Wallets |
| Anchor | Lets a payer resolve an alias, QR, account number, or merchant reference into a payment target. | Send to an Anchor |
| Schema | Defines the allowed fields for wallets, anchors, intents, and custom data. | About Schemas |
| Effect | Tells Ledger which events should notify your system. | Subscribe to Payment Events |
The P2M reference flow follows this structure: a point-of-sale system first requests a single-use payment instrument, the payer scans or enters it, the payer bank creates an intent, the hub routes the debit and credit, and the POS is notified when the payment is confirmed. In Fumadocs, that explanatory pattern is most useful as a narrative flow with swimlanes, decision points, and step-by-step sequence diagrams rather than as a standalone interactive HTML artifact.
Payment initiation and execution
The payment begins when a client creates an intent. The intent handle is your idempotency key, and the claims describe the business movement.
Client applications should not model this as a synchronous bank transfer that either finishes inside the original HTTP response or fails completely. The original POST /v2/intents creates the canonical payment instruction. The lifecycle then advances through proofs and processing until the intent becomes terminal.
Intent lifecycle
Completed payments are not reversed by editing the original intent. A post-settlement reversal is modeled as a new compensating intent or a rail-specific reversal flow. Before commit, the original flow may fail, abort, expire, or reject depending on where processing stops.
Proof generation and validation
Proofs are how Payments Hub turns authorization and external outcomes into auditable evidence.
For client mutations, bearer-token impersonation can let Ledger inject a system.auth proof for the resolved signer. SDK-based and server-side integrations may sign records directly. Bridges still submit their own proofs when they attest to external work.
Wallet and account interaction
Wallets are the Ledger addresses that receive, send, or route value. External accounts and rails are reached through bridge configuration behind those wallets.
This is why the same intent shape can support direct account payments, QR collection, alias payments, and settlement-wallet flows. The payment instruction stays stable while wallet routes, anchors, schemas, and bridges adapt it to the connected rail.
Webhook delivery
Effects deliver notifications after Ledger observes a matching event. Treat the webhook as a delivery mechanism, not as the canonical payment state.
Webhook handlers should acknowledge quickly, process asynchronously, and use the event handle for idempotency. If the payload triggers business action, your backend can read the intent or balance from Ledger before making a final decision.
Rejected payments and reversals
For client teams, the practical rule is simple: use the intent handle and Ledger reads for idempotency and status; use error reasons and proofs for diagnosis; use a new compensating flow for reversal after completion.
P2M flow pattern
The standalone P2M example is useful because it explains one flow in three layers:
| Layer | What it shows | How to adapt it in docs |
|---|---|---|
| Actor swimlanes | Payer, POS, payer bank, hub, settlement wallet, merchant bank. | Use Mermaid sequence diagrams with clear participants. |
| Decision point | Whether the merchant bank is a direct participant or settlement must happen through an intermediary wallet. | Show branch logic with Mermaid alt blocks. |
| Step detail panel | For each step: trigger, API interaction, expected state, and reconciliation evidence. | Use short prose, tables, and links to how-to pages instead of a custom interactive panel. |
A client-facing P2M walkthrough in Fumadocs should follow this outline:
- Merchant or POS mints a one-time anchor for the sale.
- Payer scans the QR or enters the alias in a participant app.
- Payer authorizes with their bank.
- Payer bank creates the intent on Ledger.
- Ledger validates, routes, prepares, commits, and records proofs.
- If the merchant bank is a participant, Ledger routes directly to that participant bridge.
- If not, Ledger credits an intermediary settlement wallet with metadata for later disbursement.
- The POS receives a payment-confirmed event after Ledger observes the committed outcome.
- Settlement, reconciliation, or batch disbursement continues outside the payer checkout wait path.
Integration checklist
- Decide which system creates wallets, anchors, intents, and effects.
- Use stable
handlevalues for idempotency across clients, intents, bridge entries, and webhook events. - Model amounts as integer minor units for the symbol.
- Keep payment-specific business context in intent or claim
customfields that are covered by schema. - Read Ledger for canonical status instead of trusting webhook delivery alone.
- Verify webhook signatures and bridge proofs when your system consumes signed records.
- Treat bridge callbacks, webhook deliveries, and client retries as duplicate-prone by design.
- Plan post-settlement reversals as separate compensating flows.
Related documentation
Subscribe to Payment Events
Register webhook effects to receive real-time notifications when payments settle, fail, or change status — no polling, no batch files.
About Signers
How cryptographic identity works on the ledger — every operation is signed, every signature is verifiable, and every participant controls their own keys.