SPEC EXTRACTION: Payment API Handler

DISCOVERED ENDPOINTS

POST /api/payments/charge
INPUT: { amount: number, currency: 'USD'|'EUR', customer_id: string, metadata: object }
OUTPUT: { id: string, status: 'pending'|'completed'|'failed', error?: string }
SIDE EFFECTS:
  -> Calls Stripe API (external)
  -> Logs to Datadog
  -> Updates customer.last_charge_at timestamp in database
ERROR HANDLING:
  -> Network timeout (>10s): retries 3x with exponential backoff
  -> Invalid amount (<0.50 USD): returns 400 'amount_too_small'
  -> Unknown customer_id: returns 404
  -> Rate limit (>100 req/min): returns 429, client backs off

GET /api/payments/status/:transaction_id
READ-ONLY, returns full transaction object including webhook_status

WEBHOOK: POST /webhooks/stripe
LISTENS FOR: charge.succeeded, charge.failed, dispute.created
ACTIONS:
  -> succeeded: marks transaction complete, updates customer credits
  -> failed: notifies customer via email, initiates retry
  -> dispute: flags account for manual review, holds balance

KNOWN QUIRKS / BUGS
-> Webhook retry logic has 24-hour window (should be 72h per Stripe docs)
-> Currency conversion cached hourly; can be stale in volatile markets
-> No idempotency key support; double-POST = double-charge risk

DEPENDENCIES
-> Stripe v2024.03.0
-> Database: PostgreSQL transactions table
-> Message queue: Redis for async webhooks
-> Auth: Bearer token in Authorization header

TYPES (inferred from usage)
type Transaction = { id, amount, currency, customer_id, status, created_at, webhook_status, metadata }

NEXT STEPS
1. Add idempotency key to prevent double-charges
2. Extend webhook retry window
3. Document this spec in README