interface PaymentEventPayload {
  eventId: string;
  userId: string;
  amountCents: number;
  currency: string;
  status: 'succeeded' | 'failed' | 'pending';
}

class PaymentEventHandler {
  constructor(
    private readonly ledger: CreditLedgerService,
    private readonly idempotencyStore: IdempotencyRepository
  ) {}

  async handle(payload: PaymentEventPayload): Promise<void> {
    const isDuplicate = await this.idempotencyStore.exists(payload.eventId);
    if (isDuplicate) return;

    if (payload.status === 'succeeded') {
      await this.ledger.appendCredit({
        userId: payload.userId,
        amount: payload.amountCents,
        source: 'payment',
        reference: payload.eventId
      });
    }

    await this.idempotencyStore.markProcessed(payload.eventId);
  }
}

interface LedgerEntry {
  id: string;
  userId: string;
  movementType: 'credit' | 'debit';
  amount: number;
  reason: string;
  referenceId: string;
  createdAt: Date;
}

class CreditLedgerService {
  constructor(private readonly db: DatabaseClient) {}

  async appendCredit(entry: Omit<LedgerEntry, 'id' | 'createdAt'>): Promise<void> {
    await this.db.ledger.insert({
      ...entry,
      movementType: 'credit',
      id: generateUuid(),
      createdAt: new Date()
    });
  }

  async appendDebit(entry: Omit<LedgerEntry, 'id' | 'createdAt'>): Promise<void> {
    await this.db.ledger.insert({
      ...entry,
      movementType: 'debit',
      id: generateUuid(),
      createdAt: new Date()
    });
  }

  async getBalance(userId: string): Promise<number> {
    const rows = await this.db.ledger.findMany({ userId });
    return rows.reduce((sum, ro

w) => { return sum + (row.movementType === 'credit' ? row.amount : -row.amount); }, 0); } }

**Rationale:** Append-only logs provide full auditability, enable safe retries, and support point-in-time balance reconstruction. They also simplify reconciliation, as every state change is traceable to a specific reference ID.

### Step 3: Decouple Usage Tracking from Payment Flows

AI consumption patterns vary widely: token streaming, image generation, agent orchestration, and batch processing. Usage recording must operate independently from payment confirmation to prevent cascading failures.

```typescript
interface UsageRecord {
  userId: string;
  actionType: 'token_generation' | 'image_render' | 'agent_execution';
  costUnits: number;
  sessionId: string;
  timestamp: Date;
}

class UsageTracker {
  constructor(
    private readonly ledger: CreditLedgerService,
    private readonly queue: MessageQueue
  ) {}

  async recordUsage(record: UsageRecord): Promise<boolean> {
    const currentBalance = await this.ledger.getBalance(record.userId);
    if (currentBalance < record.costUnits) {
      return false;
    }

    await this.ledger.appendDebit({
      userId: record.userId,
      amount: record.costUnits,
      reason: record.actionType,
      referenceId: record.sessionId
    });

    await this.queue.publish('usage.events', record);
    return true;
  }
}

Rationale: Separating usage tracking from payment handling allows the system to scale consumption recording independently. Publishing usage events to a message queue enables downstream analytics, rate limiting, and batched reconciliation without blocking the inference pipeline.

Step 4: Enforce Internal Entitlement Checks

Access control must never query the payment provider directly. Payment success does not equal access truth due to async delays, webhook failures, and network partitions. The application must maintain an internal entitlement cache that reflects the ledger state.

class EntitlementService {
  constructor(
    private readonly ledger: CreditLedgerService,
    private readonly cache: DistributedCache
  ) {}

  async canExecute(userId: string, requiredUnits: number): Promise<boolean> {
    const cached = await this.cache.get(`entitlement:${userId}`);
    if (cached) {
      return Number(cached) >= requiredUnits;
    }

    const balance = await this.ledger.getBalance(userId);
    await this.cache.set(`entitlement:${userId}`, balance, { ttl: 300 });
    return balance >= requiredUnits;
  }
}

Rationale: Internal entitlement checks eliminate access drift during payment network latency. Caching reduces ledger read pressure while maintaining consistency through short TTLs and cache invalidation on ledger mutations.

Step 5: Deploy Automated Reconciliation

State drift is inevitable in distributed systems. Scheduled reconciliation jobs must cross-check payment provider records, ledger balances, and usage logs to detect and correct anomalies.

class ReconciliationEngine {
  constructor(
    private readonly stripeClient: StripeClient,
    private readonly ledger: CreditLedgerService,
    private readonly alerting: MonitoringService
  ) {}

  async runDailySync(): Promise<void> {
    const stripeInvoices = await this.stripeClient.listSuccessfulCharges();
    const ledgerEntries = await this.ledger.findAllCredits();

    const missing = stripeInvoices.filter(
      invoice => !ledgerEntries.some(entry => entry.referenceId === invoice.id)
    );

    if (missing.length > 0) {
      await this.alerting.trigger('reconciliation.missing_credits', { count: missing.length });
      for (const invoice of missing) {
        await this.ledger.appendCredit({
          userId: invoice.userId,
          amount: invoice.amount,
          reason: 'reconciliation_correction',
          referenceId: invoice.id
        });
      }
    }
  }
}

Rationale: Reconciliation acts as a safety net for async failures, missed webhooks, and partial processing. Automated correction jobs reduce manual intervention and maintain long-term balance accuracy.

Pitfall Guide

1. Direct Webhook-to-Database Mutation

Explanation: Mutating user balances immediately upon receiving a payment webhook ignores the provider's retry semantics. Duplicate events corrupt balances. Fix: Route all payment signals through an idempotency layer. Store processed event IDs and reject duplicates before ledger interaction.

2. Single-Column Balance Counters

Explanation: Read-modify-write operations on a single integer field fail under concurrent deductions. Race conditions produce negative balances or lost credits. Fix: Replace counters with an append-only ledger. Calculate balances by summing historical entries, or use database-level optimistic locking with version columns.

3. Treating Payment Success as Access Truth

Explanation: Payment networks operate asynchronously. A successful checkout does not guarantee immediate webhook delivery or backend processing. Fix: Maintain an internal entitlement cache derived from the ledger. Access decisions must query internal state, not external payment providers.

4. Ignoring Continuous Workload Patterns

Explanation: AI agents and streaming models consume credits incrementally. Single-point deductions fail when workloads span multiple API calls or time windows. Fix: Implement batched usage aggregation and preflight authorization. Reserve credits before execution, then settle actual consumption post-completion.

5. Skipping Scheduled Reconciliation

Explanation: Drift accumulates silently. Missed webhooks, partial failures, and network partitions create balance discrepancies that compound over time. Fix: Deploy nightly reconciliation jobs that cross-reference payment provider records, ledger entries, and usage logs. Automate correction for known patterns.

6. Coupling Usage Recording to Payment Webhooks

Explanation: Tying consumption tracking to payment events creates tight coupling. If webhooks delay or fail, usage recording stalls, breaking analytics and rate limits. Fix: Decouple usage tracking using an event-driven pipeline. Publish consumption events to a message broker and process them independently.

7. No Preflight Authorization

Explanation: Users initiate expensive AI operations without verifying available credits. Mid-execution failures waste compute resources and degrade UX. Fix: Implement preflight checks that validate balance against estimated cost before spawning inference jobs. Reserve credits atomically during execution.

Production Bundle

Action Checklist

• Implement idempotency keys for all payment webhook handlers
• Replace single-column balance fields with an append-only ledger schema
• Decouple usage tracking from payment confirmation flows
• Build internal entitlement checks that query ledger state, not Stripe
• Add preflight authorization for high-cost AI operations
• Deploy scheduled reconciliation jobs to cross-check invoices and ledger entries
• Instrument monitoring for balance drift, webhook retry rates, and ledger write latency

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
MVP / Low Traffic (<1k MAU)	Single-column counter + basic webhook handler	Simplicity outweighs consistency requirements	Low infrastructure cost, high manual reconciliation
Mid-Scale SaaS (1k-50k MAU)	Append-only ledger + internal entitlement cache	Prevents race conditions and access drift	Moderate DB storage, reduced support overhead
High-Frequency AI Agents (>50k MAU)	Ledger + event-driven usage pipeline + scheduled reconciliation	Handles continuous consumption and async failures	Higher compute for reconciliation, near-zero drift

Configuration Template

// schema.prisma (PostgreSQL)
model CreditLedgerEntry {
  id            String   @id @default(uuid())
  userId        String
  movementType  String   // "credit" | "debit"
  amount        Int
  reason        String
  referenceId   String   @unique
  createdAt     DateTime @default(now())

  @@index([userId])
  @@index([referenceId])
}

model IdempotencyKey {
  eventId   String   @id
  processedAt DateTime @default(now())
}

// docker-compose.yml (infrastructure)
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ai_billing
      POSTGRES_PASSWORD: secure_local_dev
    ports:
      - "5432:5432"
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
  rabbitmq:
    image: rabbitmq:3-management
    ports:
      - "5672:5672"
      - "15672:15672"

Quick Start Guide

1. Initialize the Ledger Schema: Run the provided Prisma schema against a PostgreSQL instance. Verify that CreditLedgerEntry and IdempotencyKey tables are created with appropriate indexes.
2. Wire the Webhook Handler: Deploy the PaymentEventHandler behind your Stripe webhook endpoint. Configure Stripe to send checkout.session.completed and invoice.payment_succeeded events. Test with Stripe CLI to simulate retries.
3. Deploy Usage Tracking: Integrate UsageTracker into your AI inference pipeline. Replace direct balance deductions with ledger debit calls. Publish usage events to RabbitMQ or SQS for downstream processing.
4. Schedule Reconciliation: Set up a cron job or cloud scheduler to run ReconciliationEngine.runDailySync() at 02:00 UTC. Monitor alerts for missing credits and verify automatic correction logs.