Stripe Interview Guide: API Design, Practical Engineering & Process

Phase 1 — Basic Charges: • Design a charge(amount, currency, source) function • Validate inputs: amount > 0, valid currency code (ISO 4217), valid source format • Store charges in memory with a unique charge ID (e.g., ch_ prefix + UUID) • Return a charge object with id, amount, currency, status, created_at Phase 2 — Refunds: • Add refund(chargeId, amount?) — optional amount for partial refunds • Validate: charge exists, charge isn't already fully refunded, refund amount <= remaining • Track total refunded amount per charge • Update charge status: 'succeeded' -> 'partially_refunded' or 'refunded' Phase 3 — Idempotency: • Accept an idempotency_key header • Store a map of idempotency_key -> response • If the same key is seen again, return the cached response without re-processing • Handle edge case: same key with different parameters (return 409 Conflict) Design Principles Stripe Values: • Consistent naming conventions (snake_case, Stripe-style prefixed IDs) • Explicit error types (InvalidAmount, ChargeNotFound, AlreadyRefunded) • Immutable charge records — never mutate, always append • API responses that are self-documenting with clear field names Stripe Tip: They watch how you evolve the code. Don't over-engineer Phase 1 for Phase 3 requirements. Build the simplest correct solution at each step, then refactor when new requirements land.

Resource Model: • Customer — billing entity with payment methods • Plan — defines price, interval (monthly/yearly), and features • Subscription — links a customer to a plan with lifecycle management • Invoice — generated per billing cycle, tracks line items and payments Core Endpoints: 1. POST /v1/subscriptions — create a new subscription 2. PATCH /v1/subscriptions/:id — update plan (upgrade/downgrade) 3. DELETE /v1/subscriptions/:id — cancel (immediate or end-of-period) 4. GET /v1/subscriptions/:id — retrieve with current status and next billing date Proration Logic for Plan Changes: • Calculate unused time on current plan as a credit • Calculate remaining time on new plan as a charge • Net the difference onto the next invoice • Example: Upgrading from $10/mo to $20/mo halfway through the cycle: - Credit: $5 (unused half of $10 plan) - Charge: $10 (remaining half of $20 plan) - Net charge: $5 added to next invoice Edge Cases to Address: • Downgrade timing: apply immediately or at period end? • Failed payment on upgrade: roll back to previous plan or enter grace period? • Free trial to paid: handle the transition with first invoice generation • Proration disabled: some businesses prefer no mid-cycle adjustments API Design Principles: • Use expansion parameters: ?expand=customer,latest_invoice • Pagination for list endpoints with cursor-based pagination • Webhook events for state changes: subscription.updated, subscription.canceled • Versioned API: /v1/ prefix with changelog for breaking changes

Why Stripe Asks This: Stripe's core product IS a developer API. They need engineers who instinctively think about the developer experience of everything they build. Strong Answer Structure: • Context: 'I built an internal SDK for our payment reconciliation service that 4 teams needed to integrate with.' • Research Phase: 'Before writing any code, I interviewed engineers from each team to understand their use cases and pain points with the existing solution. I found 3 common patterns that covered 90% of use cases.' • Design Decisions: - 'Made the simple case simple: a one-line call for the common path' - 'Used sensible defaults that could be overridden for advanced use cases' - 'Designed error messages that told you what went wrong AND how to fix it' - 'Wrote usage examples before implementation (README-driven development)' • Outcome: 'Integration time dropped from 2 days to 2 hours. The most common feedback: the error messages were so good that developers rarely needed to read the docs.' Stripe Signal: You thought about the user (other developers) first, gathered requirements, prioritized simplicity, and measured the outcome.