Convert Stripe Charge JSON to TypeScript Interfaces

A Real Stripe Charge in TypeScript

Stripe responses include enums for status, integer money amounts, freeform metadata maps, and deep nesting under payment_method_details. A naive converter loses this structure.

Example JSON (trimmed)

{
  "id": "ch_3PqW2L2eZvKYlo2C0abc1234",
  "object": "charge",
  "amount": 2500,
  "currency": "usd",
  "status": "succeeded",
  "captured": true,
  "paid": true,
  "refunded": false,
  "customer": "cus_QabcDEF",
  "metadata": { "order_id": "ord_991", "campaign": "summer-sale" },
  "payment_method_details": {
    "type": "card",
    "card": { "brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2027 }
  }
}

Generated TypeScript

interface CardDetails {
  brand: "visa" | "mastercard" | "amex" | "discover" | "jcb" | "unionpay";
  last4: string;
  exp_month: number;
  exp_year: number;
}

interface PaymentMethodDetails {
  type: "card";
  card: CardDetails;
}

interface Charge {
  id: string;
  object: "charge";
  amount: number;            // smallest currency unit (cents)
  currency: string;          // ISO 4217, lowercase
  status: "succeeded" | "pending" | "failed";
  captured: boolean;
  paid: boolean;
  refunded: boolean;
  customer: string | null;
  metadata: Record<string, string>;
  payment_method_details: PaymentMethodDetails;
}

Stripe-Specific Hints for the Converter

• amount is always an integer in the smallest unit. Type it as number, never string — even though display code may format it.
• metadata is always Record<string, string>; Stripe coerces all values to strings on ingest.
• object is a literal discriminator across Stripe resources ("charge", "customer", "refund"). Keep it as a literal so a union over all resources can narrow.
• Optional Stripe fields are usually null, not absent. Prefer customer: string | null over customer?: string.

This shape composes well with the Stripe SDK's own types if you later install stripe, but generating it from raw JSON keeps frontend bundles slim.