04 — Payments Engine

backend/payments/ — engine, providers, ledger

CEO Summary

The payments engine orchestrates all payment flows — card (Stripe, Square Terminal), crypto (Dogecoin Core, CoinRemitter), and cash. It selects providers by tenant config, posts to the ledger, and enforces idempotency. Business value: Revenue flows through here. Key metrics: Transaction volume, success rate, reconciliation status. If this breaks: POS cannot accept card/crypto; refunds fail.

Architecture

flowchart TB subgraph api [API v1] Payments[payments.routes] Invoices[invoices.routes] Transactions[transactions.routes] Webhooks[webhooks.routes] end subgraph core [Core] Engine[engine.js] Gateway[gateway.js] Registry[registry.js] Ledger[ledger.js] Idempotency[idempotency.js] end subgraph drivers [Drivers] Stripe[Stripe] StripeTerminal[Stripe Terminal] SquareTerminal[Square Terminal] DogeCore[Dogecoin Core] CoinRemitter[CoinRemitter] end Payments --> Engine Engine --> Gateway Gateway --> Registry Registry --> drivers Engine --> Ledger Engine --> Idempotency

Overview

Path: backend/payments/

Orchestrates payment flow: provider selection, charge/refund, ledger posting, idempotency.

Core Components

File	Purpose
engine.js	Charge, refund orchestration (simulation + real)
core/registry.js	Provider registry — lists available drivers
core/gateway.js	getRuntimeConfig, getRuntimeDriver — selects provider by tenant
core/ledger.js	Ledger posting
core/idempotency.js	Idempotent request handling

Providers (Drivers)

Provider	Path	Purpose
Stripe Terminal	providers/stripeTerminal.js	Card via Stripe Terminal
Coinbase Commerce	providers/coinbaseCommerce.js	Crypto payments
Dogecoin Core	providers/dogecoinCore.js	DOGE via Core node
CoinRemitter Doge	providers/coinremitterDoge.js	DOGE via CoinRemitter
GigaWallet	providers/gigawallet.js	Lightning/crypto
Internal Card	providers/internalCard.js	Internal card processing
Crypto Sim	providers/cryptoSim.js	Simulated crypto (testing)
Mock Acquirer	providers/mockAcquirer.js	Mock card (testing)
Crypto (DOGE/BTC)	providers/crypto/	index, rates, address, rpc per coin

API v1 Routes (Full)

Path: backend/payments/api/v1/

File	Purpose
payments.routes.js	Payment intents, capture
invoices.routes.js	Invoice CRUD
transactions.routes.js	Transaction list
webhooks.routes.js	Webhook handling
ledger.routes.js	Ledger entries
recon.routes.js	Reconciliation
utxo.routes.js	UTXO management (crypto)
disputes.routes.js	Disputes
intents.routes.js	Payment intents
merchants.routes.js	Merchant config
locations.routes.js	Location config
keys.routes.js	Key management
apikeys.routes.js	API keys
org.rules.routes.js	Org-level rules

Validators

Path: backend/payments/validators/

webhooks.schemas.js, invoices.schemas.js — Request validation

Provider Selection

gateway.getRuntimeConfig({ id, provider, type }) — Selects from PaymentProvider model. Priority: by id → by provider slug → by type → any enabled.