System Design: [Payment and ledger system name]

Reference design for accepting payments through external payment service providers (PSPs) and recording every money movement in a double-entry ledger. It covers idempotency keys, the payment state machine, PSP integration and webhooks, journals and postings, balances, reconciliation, exactly-once side effects through a transactional outbox, auditability and PCI DSS scope reduction. It follows the structure of the System Design Document template and is pre-filled with a worked design to adapt. Values marked Example are assumptions. This is an engineering format, not accounting, legal or regulatory advice: confirm accounting treatment and compliance scope with your finance and compliance teams.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: Our marketplace charges buyers and pays out sellers. Payment status lives in the orders table, refunds are handled by a script, and the monthly close takes finance 9 days because PSP reports do not match our data. Last quarter 0.03% of orders were charged twice after client retries.]

1.2 Proposed solution

[Example: A payment service owns a payment state machine and talks to PSPs through adapters. Every request carries an idempotency key. Every state change that moves money writes a balanced journal entry to an append-only double-entry ledger in the same database transaction as the state change and an outbox record. Outbox relays perform PSP calls and publish events exactly once in effect. A reconciliation job matches ledger entries against PSP settlement reports daily and opens cases for every difference. Card data never touches our servers: clients tokenise through the PSP's hosted fields.]

1.3 Decisions requested from reviewers

2. Requirements

2.1 Functional requirements

2.2 Non-functional requirements

2.3 Out of scope

• [Example: seller payouts to bank accounts (next design, reuses the ledger)]
• [Example: multi-currency FX conversion inside the ledger]
• [Example: tax calculation]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Throughput

Ledger postings:

These rates fit a single well-provisioned relational primary; correctness, not throughput, is the driver of this design.

3.3 Storage

Postings older than the current and previous fiscal year move to partitioned archive tables (still queryable for audit), keeping the hot set near 16 TB.

3.4 PSP connections

With PSP authorisation latency $t_{psp} \approx 800$ ms, concurrent in-flight calls at peak are, by Little's law:

Size the outbound connection pool and PSP rate-limit agreement for at least twice that.

3.5 Summary

4. API design

4.1 Endpoints

4.2 Request and response examples

Create a payment with a PSP token obtained client side; amounts are integers in minor units:

POST /v1/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: ord_88123-attempt-1

{"orderId": "ord_88123", "amount": 4599, "currency": "EUR", "paymentMethodToken": "pm_tok_3fa9", "captureMode": "manual", "sellerAccountId": "acct_s_211"}

HTTP/1.1 201 Created
Content-Type: application/json

{"id": "pay_01JA2", "state": "authorized", "amount": 4599, "currency": "EUR", "pspReference": "psp_7712", "authorizedAt": "2026-03-14T10:02:03Z"}

4.3 Idempotency semantics and errors

The server stores (client_id, idempotency_key) with a hash of the request body and the final response. A repeated key with the same body returns the stored response; with a different body it returns 422. A repeated key while the first request is still running returns 409 so the client retries later.

• Versioning: /v1 path; money fields never change type within a version.

5. Data model

5.1 Entities

Payments and their attempts hold operational state; journal entries and postings form the immutable ledger; the outbox links them to the outside world.

5.2 Storage choices and invariants

Amounts are signed 64-bit integers in minor units with an ISO 4217 currency code; floating-point types are forbidden in money paths. A database trigger or deferred constraint rejects a journal entry whose postings do not sum to zero.

5.3 Chart of accounts (excerpt)

6. High-level design

All money state lives in one transactional database; everything that talks to the outside world is driven from the outbox.

7. Detailed design

7.1 Authorise path (critical path)

For a synchronous checkout response the payment service calls the PSP inline after committing the intent, and the outbox guarantees a retry if it crashes.

The PSP idempotency key is our payment_id plus operation, so a retried call after a timeout returns the original PSP result rather than charging again. If a PSP does not support idempotency keys, the relay first queries the PSP by our reference before retrying.

7.2 Payment state machine

States change only through the transitions below; each transition is one database transaction that also writes the matching journal entry and outbox events.

Out-of-order webhooks (for example "captured" arriving before our capture call returns) are applied only if the transition is valid from the current state; otherwise they are stored and re-evaluated, never dropped.

7.3 Exactly-once effects through the outbox

Delivery between systems is at-least-once; effects are exactly-once because every receiver is idempotent:

1. The state change, journal entry and outbox row commit in one transaction. There is no moment where money moved in our books but no event exists.
2. The relay publishes or calls, then marks the row done. A crash between the two repeats the call; the PSP idempotency key and consumer deduplication by event ID absorb the repeat.
3. Consumers (order service, notifications) store processed event IDs in the same transaction as their own effect.

7.4 Double-entry ledger

Every journal entry has at least two postings and sums to zero per currency (debits positive, credits negative in this convention). For a EUR 45.99 payment with a 10% platform fee and a EUR 0.35 PSP fee:

Check: capture $45.99 - 41.39 - 4.60 = 0$; settlement $45.64 + 0.35 - 45.99 = 0$. The fee split (whether the fee is rounded down, and who bears PSP fees) is a finance decision; record it in the chart of accounts.

Corrections never edit postings. A wrong entry is cancelled by a reversing entry (reverses_entry_id) and replaced by a correct one, so the history of what we believed and when stays visible to auditors.

7.5 Balances and the consistency model

• Strong consistency inside the ledger: postings and balance updates commit together; the account row's version is checked (optimistic concurrency) so concurrent entries cannot lose updates.
• Point-in-time balances are the sum of postings with effective_at <= asOf, served from daily closing snapshots plus the delta.
• Hot accounts such as platform_fee_revenue receive a posting for almost every payment. They are split into Example: 16 sub-accounts chosen by hash of payment_id; reports sum the sub-accounts.
• Eventual consistency with the outside world: PSP and bank state converge through webhooks and reconciliation; the ledger records what we know, with effective_at set to when the event happened.

7.6 Reconciliation

7.7 Auditability and PCI DSS scope reduction

• Ledger tables are append-only; the application database role has no UPDATE or DELETE grant on them. Every entry records actor, request ID and source event.
• A nightly job recomputes balances from postings and compares them to stored balances and to a chained hash of the day's entries.
• Card numbers are entered into PSP-hosted fields or a redirect page, so our systems receive only tokens. This is designed to keep our environment in the reduced PCI DSS self-assessment scope; confirm the exact scope with a qualified assessor.

8. Scalability and performance

Latency budget for create-and-authorise (target p99 2.5 s):

9. Reliability, security and operations

9.1 Failure modes

9.2 Security and abuse

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Rollout and rollback

[Example: Run the ledger in shadow mode, deriving entries from the old system's events, and compare balances daily. Move new payments per merchant cohort. Rollback routes new payments to the old path; payments already created complete in the new system.]

11.3 Risks

12. Appendices

12.1 Open questions

12.2 Glossary

12.3 References

Standard and licence note

Based on common industry practice for payment systems and double-entry bookkeeping, and on the references in 12.3. This is a reference design to adapt, with illustrative numbers; it is a format, not accounting, legal or regulatory advice. Original text written for this collection; no text from PCI DSS or other standards is reproduced. Template licence: MIT.