Forge payments

forge-payments: Payments

Purpose

Audit money movement, pricing, entitlements, provider events, reconciliation, idempotency, and sensitive data boundaries.

This is an agent playbook, not a claim of standalone analyzer coverage. Apply

fullstack-forge/references/shared/module-contract.md

for common applicability, evidence, command-safety, mutation, verification, and completion rules.

Never hide failed checks or claim that an operation ran when it did not.

Automatic activation signals

Activate when a request or direct repository evidence involves payments, when the user explicitly names forge-payments, or when discovery proves an applicable boundary.

• Payments, billing, subscriptions, refunds, credits, invoices, or financial ledgers

When not to activate

• No money, stored value, pricing, or paid entitlement

Automated support

Relevant discovery inputs are:

• payment routes and provider integration
• pricing and ledger models
• webhook handlers

Available deterministic support, where present:

• Use inspect-routes for its bounded evidence when present; treat unavailable runtime evidence as NOT_VERIFIED.

Agent inspection procedure

1. Trace amount determination: every charge, refund, and credit derives from server-owned records, never client input.
2. Verify precision: minor-unit or decimal arithmetic, documented rounding, and tax and discount ordering.
3. Inspect webhooks: raw-byte signature verification before parsing, durable event-ID idempotency before side effects, and out-of-order tolerance.
4. Map the payment state machine: legal transitions, partial-failure recovery, and reconciliation against provider records.
5. Check test/live separation, sensitive-data boundaries (hosted fields), refund and dispute paths, and the audit trail for money movement.

Manual inspection requirements:

• Review provider dashboard settings and sample reconciliations
• Obtain qualified compliance and financial review where applicable

Stack-specific guidance:

• Use provider-hosted collection where possible and never trust client-calculated amounts

Evidence to collect

For formal findings, also follow fullstack-forge/references/PROTOCOL.md. Record the module's inspected boundary, relevant tests, direct observations, and unavailable evidence.

Primary standards used as criteria, not proof of compliance:

• OWASP Third Party Payment Gateway Integration Cheat Sheet
• PCI DSS scope concepts

Common production failures

• Trace quote-to-entitlement and refund/dispute flows with currency and minor-unit handling
• Inspect server-authoritative amounts, idempotency, webhook raw-body signatures, replay defense, ordering, duplicate events, state machines, and reconciliation
• Check authorization, audit trails, secrets, hosted-field boundaries, tax/discount rounding, negative amounts, and failure recovery

Missing-control checks

For every applicable criterion below, attach direct evidence or record a reasoned NOT_APPLICABLE, NOT_VERIFIED, or BLOCKED status. The list is a routing checklist, not evidence by itself.

• Server-side amount calculation
• Currency precision
• Rounding
• Webhook signatures
• Idempotency
• Duplicate payments
• Reconciliation
• Refunds
• Partial failures
• Payment state machines
• Client-side tampering
• Test and live separation
• Sensitive data
• Audit trails
• Replay attacks
• Price changes
• Subscription transitions
• Chargeback handling
• Webhook ordering

Commands and tools

• Run forge payments audit --json or fullstack-forge payments audit --json when an explicit audit is requested and the CLI is installed. Normal feature work does not require it.
• Use the deterministic support named above only for its documented bounded evidence.

Safe fixes

• Add idempotency storage, explicit currency validation, and duplicate-event tests
• Redact payment identifiers from logs

Approval-required changes

• Changing financial calculations, prices, ledgers, provider, settlement, or entitlement semantics

Verification

• Run sandbox success, duplicate, timeout, delayed webhook, refund, and dispute scenarios
• Reconcile provider, internal ledger, and granted entitlement

Completion contract

Apply the shared module contract and the module-specific limitations below.

Known limitations

• Do not claim PCI or financial compliance from a code audit