Write every payment event — intent created, authorized, captured, failed, refunded — to an append-only store; use a write-once data structure (e.g., an insert-only DB table with no UPDATE/DELETE permissions for the application role, or an object store with versioning and no-delete policy).
Each log record must include: timestamp (UTC, server-generated), agent session ID, human principal ID, merchant identifier, amount, currency, PSP transaction ID, idempotency key, and the authorization context (which scoped token or approval was used).
Store the full PSP response payload (minus card numbers) alongside your structured fields — raw PSP data is the ground truth for disputes and reconciliation.
Run a nightly reconciliation job: pull the PSP's transaction list for the period, match each entry to an audit log record by PSP transaction ID, and flag any PSP transaction with no matching log record (ghost charges) or any log record with no PSP match (phantom records).
Expose a read-only reconciliation report per billing period to the human account owner; flag unmatched items and anomalies rather than silently resolving them.
For compliance, retain audit records for at least the period required by your jurisdiction and card network rules — typically 5–7 years for financial records.
Known gotchas
Application-level 'immutability' is not true immutability — a compromised backend can still delete rows; for high-value audit trails, append records to a secondary store (e.g., a WORM S3 bucket or a write-once ledger) that the primary application cannot delete from.
PSP transaction IDs are not always stable across disputes and refunds — a charge can acquire multiple related IDs (charge ID, refund ID, dispute ID); model these as a graph of related events, not a single row.
Reconciliation against card statements requires the settled amount, which may differ from the authorized amount due to currency conversion or partial captures — store both the authorization amount and the settled amount.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp