How to onboard to acme-payments-api

A payments API that authorizes charges, records them in a double-entry ledger, batches merchant payouts, and reconciles card-processor events through idempotent webhooks.

A money-movement service where correctness and idempotency are the whole game: the ledger must always balance and every retry must be safe.

First files to read

The fastest way into acme-payments-api: read these 5 files first, in order.

1. 1src/charges/chargeService.tsEntry point for authorizing a charge
2. 2src/ledger/ledger.tsDouble-entry posting logic, the money-safety core
3. 3src/webhooks/handler.tsIdempotent webhook reconciliation
4. 4src/payouts/batch.tsNightly payout batching
5. 5src/db/schema.sqlLedger and charges schema, with constraints

Main systems

Key terms

Double-entry

Every transaction posts equal debits and credits so the ledger always sums to zero.

Idempotency key

A client-supplied token that makes a retried request safe to process exactly once.

Payout

Moving a merchant balance out to their bank account.

Reconciliation

Bringing internal state in line with the processor via webhook events.

More sample repositories