Design a Payment System

14 collapsed lines
1
import { Redis } from "ioredis"
2
import { createHash } from "crypto"
3

4
interface IdempotencyRecord {
5
  key: string
6
  request_hash: string
7
  response: any
8
  status: "processing" | "complete" | "error"
9
  created_at: Date
10
  expires_at: Date
11
}
12

13
const redis = new Redis(process.env.REDIS_URL)
14
const IDEMPOTENCY_TTL = 24 * 60 * 60 // 24 hours (Stripe's window)
15

16
export async function checkIdempotency(
17
  key: string,
18
  requestBody: object,
19
): Promise<{ exists: boolean; response?: any; conflict?: boolean }> {
20
  const requestHash = hashRequest(requestBody)
21

22
  // Check Redis first (fast path)
23
  const cached = await redis.get(`idem:${key}`)
24

25
  if (!cached) {
26
    // Key doesn't exist, allow processing
27
    return { exists: false }
28
  }
29

30
  const record: IdempotencyRecord = JSON.parse(cached)
31

32
  // Key exists, check if parameters match
33
  if (record.request_hash !== requestHash) {
34
    // Same key, different request = conflict
35
    return { exists: true, conflict: true }
36
  }
37

38
  // Same key, same request
39
  if (record.status === "processing") {
40
    // Request in flight, return 409 to trigger retry
41
    return { exists: true, conflict: true }
42
  }
43

44
  // Return cached response
45
  return { exists: true, response: record.response }
46
}
47

48
export async function startIdempotentRequest(key: string, requestBody: object): Promise<boolean> {
49
  const requestHash = hashRequest(requestBody)
50

51
  // Atomic set-if-not-exists
52
  const result = await redis.set(
53
    `idem:${key}`,
54
    JSON.stringify({
55
      key,
56
      request_hash: requestHash,
57
      status: "processing",
58
      created_at: new Date(),
59
    }),
60
    "EX",
61
    IDEMPOTENCY_TTL,
62
    "NX", // Only set if not exists
63
  )
16 collapsed lines
64

65
  return result === "OK"
66
}
67

68
export async function completeIdempotentRequest(
69
  key: string,
70
  response: any,
71
  status: "complete" | "error",
72
): Promise<void> {
73
  const cached = await redis.get(`idem:${key}`)
74
  if (!cached) return
75

76
  const record: IdempotencyRecord = JSON.parse(cached)
77
  record.response = response
78
  record.status = status
79

80
  await redis.setex(`idem:${key}`, IDEMPOTENCY_TTL, JSON.stringify(record))
81

82
  // Also persist to PostgreSQL for durability
83
  await db.idempotency_records.upsert({
84
    key,
85
    request_hash: record.request_hash,
86
    response: JSON.stringify(response),
87
    status,
88
    expires_at: new Date(Date.now() + IDEMPOTENCY_TTL * 1000),
89
  })
90
}
91

92
function hashRequest(body: object): string {
93
  return createHash("sha256").update(JSON.stringify(body)).digest("hex")
94
}

7 collapsed lines
1
import { checkIdempotency, startIdempotentRequest, completeIdempotentRequest } from "./idempotency-service"
2

3
export async function createPayment(req: Request): Promise<Response> {
4
  const idempotencyKey = req.headers.get("Idempotency-Key")
5

6
  if (!idempotencyKey) {
7
    return errorResponse(400, "idempotency_key_required")
8
  }
9

10
  // Check for existing request
11
  const check = await checkIdempotency(idempotencyKey, req.body)
12

13
  if (check.conflict) {
14
    return errorResponse(409, "idempotency_conflict")
15
  }
16

17
  if (check.exists && check.response) {
18
    // Return cached response (including errors)
19
    return new Response(JSON.stringify(check.response), {
20
      status: check.response.status_code || 200,
21
      headers: { "Idempotent-Replayed": "true" },
22
    })
23
  }
24

25
  // Start processing (atomic lock)
26
  const acquired = await startIdempotentRequest(idempotencyKey, req.body)
27
  if (!acquired) {
28
    // Another request is processing, retry later
29
    return errorResponse(409, "request_in_progress")
30
  }
31

32
  try {
33
    // Process payment
34
    const payment = await processPayment(req.body)
35

36
    // Cache successful response
37
    await completeIdempotentRequest(idempotencyKey, payment, "complete")
38

39
    return successResponse(201, payment)
40
  } catch (error) {
41
    // Cache error response (prevents retry storms)
42
    await completeIdempotentRequest(idempotencyKey, { error: error.message }, "error")
43

44
    throw error
45
  }
46
}

9 collapsed lines
1
interface ThreeDSResult {
2
  authentication_status: "success" | "failed" | "attempted" | "not_supported"
3
  liability_shift: boolean
4
  eci: string // Electronic Commerce Indicator
5
}
6

7
export async function handle3DSChallenge(
8
  paymentIntentId: string,
9
  returnUrl: string,
10
): Promise<{ requires_action: boolean; redirect_url?: string }> {
11
  const pi = await stripe.paymentIntents.retrieve(paymentIntentId)
12

13
  if (pi.status === "requires_action") {
14
    // 3DS challenge required
15
    return {
16
      requires_action: true,
17
      redirect_url: pi.next_action?.redirect_to_url?.url,
18
    }
19
  }
20

21
  return { requires_action: false }
22
}

14 collapsed lines
1
interface SettlementRecord {
2
  external_id: string
3
  amount_cents: number
4
  currency: string
5
  type: "charge" | "refund" | "chargeback"
6
  settled_at: Date
7
  fees_cents: number
8
}
9

10
interface ReconciliationResult {
11
  matched: number
12
  unmatched_internal: SettlementRecord[]
13
  unmatched_external: SettlementRecord[]
14
  amount_discrepancy_cents: number
15
}
16

17
export async function reconcileSettlement(date: Date, processor: string): Promise<ReconciliationResult> {
18
  // 1. Fetch processor settlement report
19
  const externalRecords = await fetchSettlementReport(processor, date)
20

21
  // 2. Fetch internal ledger entries
22
  const internalRecords = await fetchLedgerEntries(date, processor)
23

24
  // 3. Match by external ID
25
  const matched: string[] = []
26
  const unmatchedExternal: SettlementRecord[] = []
27
  const unmatchedInternal: SettlementRecord[] = []
28

29
  const internalMap = new Map(internalRecords.map((r) => [r.external_id, r]))
30

31
  for (const ext of externalRecords) {
32
    const internal = internalMap.get(ext.external_id)
33

34
    if (!internal) {
35
      // Transaction in processor report but not in our ledger
36
      unmatchedExternal.push(ext)
37
      continue
38
    }
39

40
    // Verify amounts match
41
    if (internal.amount_cents !== ext.amount_cents) {
42
      unmatchedExternal.push(ext)
43
      unmatchedInternal.push(internal)
44
      continue
45
    }
46

47
    matched.push(ext.external_id)
48
    internalMap.delete(ext.external_id)
49
  }
50

51
  // Remaining internal records not in processor report
52
  for (const [, record] of internalMap) {
53
    unmatchedInternal.push(record)
54
  }
55

56
  // Calculate total discrepancy
57
  const externalTotal = externalRecords.reduce((sum, r) => sum + r.amount_cents, 0)
58
  const internalTotal = internalRecords.reduce((sum, r) => sum + r.amount_cents, 0)
59

60
  return {
61
    matched: matched.length,
62
    unmatched_internal: unmatchedInternal,
63
    unmatched_external: unmatchedExternal,
64
    amount_discrepancy_cents: externalTotal - internalTotal,
65
  }
66
}
67

68
// Alert on discrepancies
16 collapsed lines
69
export async function handleReconciliationBreaks(result: ReconciliationResult): Promise<void> {
70
  if (result.unmatched_external.length > 0) {
71
    await alertFinanceTeam({
72
      type: "unmatched_external",
73
      count: result.unmatched_external.length,
74
      transactions: result.unmatched_external,
75
    })
76
  }
77

78
  if (Math.abs(result.amount_discrepancy_cents) > 100) {
79
    // $1 threshold
80
    await alertFinanceTeam({
81
      type: "amount_discrepancy",
82
      amount_cents: result.amount_discrepancy_cents,
83
    })
84
  }
85
}

11 collapsed lines
1
interface RoutingDecision {
2
  processor: "stripe" | "adyen" | "paypal"
3
  reason: string
4
  expected_auth_rate: number
5
  expected_cost_bps: number // basis points
6
}
7

8
interface TransactionContext {
9
  card_brand: string
10
  card_country: string
11
  card_funding: "credit" | "debit" | "prepaid"
12
  amount_cents: number
13
  currency: string
14
  merchant_country: string
15
}
16

17
export function routeTransaction(ctx: TransactionContext): RoutingDecision {
18
  // Rule 1: US debit cards - route to lowest-cost network
19
  if (ctx.card_country === "US" && ctx.card_funding === "debit") {
20
    return {
21
      processor: "adyen", // Intelligent routing for US debit
22
      reason: "us_debit_cost_optimization",
23
      expected_auth_rate: 0.96,
24
      expected_cost_bps: 50, // vs 150+ for credit
25
    }
26
  }
27

28
  // Rule 2: European cards - route to Adyen for local acquiring
29
  if (["DE", "FR", "GB", "NL", "ES", "IT"].includes(ctx.card_country)) {
30
    return {
31
      processor: "adyen",
32
      reason: "eu_local_acquiring",
33
      expected_auth_rate: 0.94,
34
      expected_cost_bps: 180, // Lower cross-border fees
35
    }
36
  }
37

38
  // Rule 3: High-value transactions - route to processor with best auth rate
39
  if (ctx.amount_cents > 100000) {
40
    // > $1000
41
    return {
42
      processor: "stripe",
43
      reason: "high_value_auth_optimization",
44
      expected_auth_rate: 0.92,
45
      expected_cost_bps: 290,
46
    }
47
  }
48

49
  // Default: Stripe
50
  return {
51
    processor: "stripe",
52
    reason: "default",
53
    expected_auth_rate: 0.9,
16 collapsed lines
54
    expected_cost_bps: 290,
55
  }
56
}
57

58
// Failover on processor error
59
export async function processWithFailover(ctx: TransactionContext, paymentData: PaymentData): Promise<PaymentResult> {
60
  const primary = routeTransaction(ctx)
61
  const processors = [primary.processor, ...getFailoverProcessors(primary.processor)]
62

63
  for (const processor of processors) {
64
    try {
65
      return await processPayment(processor, paymentData)
66
    } catch (error) {
67
      if (isRetryableError(error)) {
68
        continue // Try next processor
69
      }
70
      throw error // Non-retryable (e.g., card declined)
71
    }
72
  }
73

74
  throw new Error("All processors failed")
75
}

9 collapsed lines
1
import { loadStripe } from "@stripe/stripe-js"
2

3
export async function handle3DSChallenge(clientSecret: string): Promise<{ success: boolean; error?: string }> {
4
  const stripe = await loadStripe(process.env.NEXT_PUBLIC_STRIPE_KEY)
5

6
  // This opens the 3DS challenge in a modal/redirect
7
  const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
8
    payment_method: paymentMethodId,
9
  })
10

11
  if (error) {
12
    // 3DS failed or user canceled
13
    return { success: false, error: error.message }
14
  }
15

16
  if (paymentIntent.status === "succeeded") {
17
    return { success: true }
18
  }
19

20
  if (paymentIntent.status === "requires_action") {
21
    // Additional action needed (rare edge case)
22
    return await handle3DSChallenge(paymentIntent.client_secret)
23
  }
24

25
  return { success: false, error: "Unexpected payment status" }
26
}

1
const ERROR_MESSAGES: Record<string, string> = {
2
  card_declined: "Your card was declined. Please try a different card.",
3
  insufficient_funds: "Insufficient funds. Please try a different card.",
4
  expired_card: "Your card has expired. Please update your payment method.",
5
  incorrect_cvc: "The CVC code is incorrect. Please check and try again.",
6
  processing_error: "A processing error occurred. Please try again.",
7
  rate_limited: "Too many attempts. Please wait a moment and try again.",
8
}
9

10
export function getErrorMessage(declineCode: string): string {
11
  return ERROR_MESSAGES[declineCode] || "Payment failed. Please try again."
12
}