1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

// ============================================
// Common Interface (Port)
// ============================================
 
interface PaymentGateway {
  readonly name: string;
  readonly supportedMethods: PaymentMethodType[];
  readonly supportedCurrencies: string[];
  
  // Core payment operations
  authorize(request: AuthorizeRequest): Promise<AuthorizeResponse>;
  capture(request: CaptureRequest): Promise<CaptureResponse>;
  void(request: VoidRequest): Promise<VoidResponse>;
  refund(request: RefundRequest): Promise<RefundResponse>;
  
  // Tokenization
  tokenize(request: TokenizeRequest): Promise<TokenizeResponse>;
  deleteToken(tokenId: string): Promise<void>;
  
  // Health & status
  healthCheck(): Promise<HealthStatus>;
  getTransaction(transactionId: string): Promise<TransactionDetails>;
}
 
interface AuthorizeRequest {
  idempotencyKey: string;
  amount: number;          // In smallest currency unit
  currency: string;        // ISO 4217
  paymentMethod: PaymentMethodToken;
  merchantReference: string;
  capture: boolean;        // Auth-only or auth+capture
  metadata?: Record<string, string>;
  
  // For fraud detection
  customerIp?: string;
  billingAddress?: Address;
  shippingAddress?: Address;
  
  // 3D Secure
  threeDSecure?: ThreeDSecureParams;
}
 
interface AuthorizeResponse {
  gatewayTransactionId: string;
  status: GatewayTransactionStatus;
  authorizationCode?: string;
  networkTransactionId?: string;
  
  // For 3DS challenges
  redirectUrl?: string;
  requiresAction?: boolean;
  
  // Risk assessment
  riskScore?: number;
  riskAssessment?: RiskAssessment;
  
  // Error details if failed
  declineCode?: string;
  declineReason?: string;
  
  // Raw response for debugging
  rawResponse?: object;
}
 
type GatewayTransactionStatus = 
  | 'authorized'
  | 'captured'
  | 'declined'
  | 'pending'
  | 'requires_action'
  | 'error';

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

import Stripe from 'stripe';
 
class StripeGatewayAdapter implements PaymentGateway {
  readonly name = 'stripe';
  readonly supportedMethods: PaymentMethodType[] = [
    'card', 'apple_pay', 'google_pay', 'sepa_debit', 'us_bank_account'
  ];
  readonly supportedCurrencies = ['USD', 'EUR', 'GBP', 'CAD', /* 135+ currencies */];
  
  private client: Stripe;
  
  constructor(config: StripeConfig) {
    this.client = new Stripe(config.secretKey, {
      apiVersion: '2023-10-16',
      timeout: 10000,  // 10 second timeout
      maxNetworkRetries: 2,
    });
  }
  
  async authorize(request: AuthorizeRequest): Promise<AuthorizeResponse> {
    try {
      // Translate our request to Stripe's format
      const stripeRequest: Stripe.PaymentIntentCreateParams = {
        amount: request.amount,
        currency: request.currency.toLowerCase(),
        payment_method: request.paymentMethod.token,
        confirm: true,
        capture_method: request.capture ? 'automatic' : 'manual',
        metadata: {
          ...request.metadata,
          merchant_reference: request.merchantReference,
          idempotency_key: request.idempotencyKey,
        },
      };
      
      // Add 3DS parameters if required
      if (request.threeDSecure) {
        stripeRequest.payment_method_options = {
          card: {
            request_three_d_secure: request.threeDSecure.required 
              ? 'any' 
              : 'automatic',
          },
        };
      }
      
      // Make the API call with idempotency key
      const intent = await this.client.paymentIntents.create(
        stripeRequest,
        { idempotencyKey: request.idempotencyKey }
      );
      
      // Translate Stripe response to our format
      return this.mapStripeIntentToResponse(intent);
      
    } catch (error) {
      return this.handleStripeError(error);
    }
  }
  
  private mapStripeIntentToResponse(
    intent: Stripe.PaymentIntent
  ): AuthorizeResponse {
    // Map Stripe status to our normalized status
    const statusMap: Record<string, GatewayTransactionStatus> = {
      'requires_payment_method': 'declined',
      'requires_confirmation': 'pending',
      'requires_action': 'requires_action',
      'processing': 'pending',
      'requires_capture': 'authorized',
      'canceled': 'declined',
      'succeeded': 'captured',
    };
    
    return {
      gatewayTransactionId: intent.id,
      status: statusMap[intent.status] || 'error',
      authorizationCode: intent.charges?.data[0]?.payment_method_details
        ?.card?.authorization_code,
      networkTransactionId: intent.charges?.data[0]
        ?.payment_method_details?.card?.network_transaction_id,
      redirectUrl: intent.next_action?.redirect_to_url?.url,
      requiresAction: intent.status === 'requires_action',
      rawResponse: intent,
    };
  }
  
  private handleStripeError(error: unknown): AuthorizeResponse {
    if (error instanceof Stripe.errors.StripeCardError) {
      return {
        gatewayTransactionId: '',
        status: 'declined',
        declineCode: error.decline_code || error.code,
        declineReason: error.message,
      };
    }
    
    if (error instanceof Stripe.errors.StripeAPIError) {
      // Log and potentially retry
      throw new GatewayUnavailableError('stripe', error.message);
    }
    
    throw error;
  }
  
  // ... other methods (capture, void, refund, tokenize)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

class AdyenGatewayAdapter implements PaymentGateway {
  readonly name = 'adyen';
  readonly supportedMethods: PaymentMethodType[] = [
    'card', 'ideal', 'bancontact', 'sofort', 'klarna', 'alipay'
  ];
  readonly supportedCurrencies = ['USD', 'EUR', 'GBP', /* 150+ currencies */];
  
  private baseUrl: string;
  private apiKey: string;
  private merchantAccount: string;
  
  constructor(config: AdyenConfig) {
    this.baseUrl = config.isLive
      ? 'https://checkout-live.adyen.com/v70'
      : 'https://checkout-test.adyen.com/v70';
    this.apiKey = config.apiKey;
    this.merchantAccount = config.merchantAccount;
  }
  
  async authorize(request: AuthorizeRequest): Promise<AuthorizeResponse> {
    // Adyen uses a different request structure
    const adyenRequest = {
      amount: {
        value: request.amount,
        currency: request.currency,
      },
      reference: request.merchantReference,
      paymentMethod: {
        storedPaymentMethodId: request.paymentMethod.token,
      },
      merchantAccount: this.merchantAccount,
      shopperInteraction: 'ContAuth',
      recurringProcessingModel: 'CardOnFile',
      captureDelayHours: request.capture ? 0 : undefined,
    };
    
    const response = await fetch(`${this.baseUrl}/payments`, {
      method: 'POST',
      headers: {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json',
        'Idempotency-Key': request.idempotencyKey,
      },
      body: JSON.stringify(adyenRequest),
    });
    
    const result = await response.json();
    
    return this.mapAdyenResponse(result);
  }
  
  private mapAdyenResponse(result: AdyenPaymentResponse): AuthorizeResponse {
    // Adyen uses different result codes
    const statusMap: Record<string, GatewayTransactionStatus> = {
      'Authorised': 'authorized',
      'Captured': 'captured',
      'Refused': 'declined',
      'Pending': 'pending',
      'RedirectShopper': 'requires_action',
      'ChallengeShopper': 'requires_action',
      'Error': 'error',
    };
    
    return {
      gatewayTransactionId: result.pspReference || '',
      status: statusMap[result.resultCode] || 'error',
      declineCode: result.refusalReasonCode,
      declineReason: result.refusalReason,
      redirectUrl: result.action?.url,
      requiresAction: result.action != null,
      rawResponse: result,
    };
  }
}
 
// Factory for creating appropriate adapter
class GatewayFactory {
  private adapters: Map<string, PaymentGateway> = new Map();
  
  constructor(configs: GatewayConfigs) {
    if (configs.stripe) {
      this.adapters.set('stripe', new StripeGatewayAdapter(configs.stripe));
    }
    if (configs.adyen) {
      this.adapters.set('adyen', new AdyenGatewayAdapter(configs.adyen));
    }
    if (configs.braintree) {
      this.adapters.set('braintree', new BraintreeGatewayAdapter(configs.braintree));
    }
  }
  
  getGateway(name: string): PaymentGateway {
    const gateway = this.adapters.get(name);
    if (!gateway) {
      throw new Error(`Unknown gateway: ${name}`);
    }
    return gateway;
  }
  
  getAvailableGateways(): PaymentGateway[] {
    return Array.from(this.adapters.values());
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

interface RoutingDecision {
  primaryGateway: string;
  fallbackGateways: string[];
  reason: string;
}
 
interface RoutingContext {
  amount: number;
  currency: string;
  paymentMethod: PaymentMethodType;
  cardNetwork?: CardNetwork;  // visa, mastercard, amex
  cardCountry?: string;       // Issuing country
  merchantCountry: string;
  merchantCategory: string;   // MCC code
  isRecurring: boolean;
  riskScore?: number;
}
 
class GatewayRouter {
  private gateways: Map<string, PaymentGateway>;
  private routingRules: RoutingRule[];
  private gatewayHealth: Map<string, CircuitBreaker>;
  private successRates: Map<string, GatewaySuccessRate>;
  
  constructor(
    gateways: Map<string, PaymentGateway>,
    config: RoutingConfig
  ) {
    this.gateways = gateways;
    this.routingRules = config.rules;
    this.gatewayHealth = this.initializeCircuitBreakers(gateways);
    this.successRates = new Map();
  }
  
  selectGateway(context: RoutingContext): RoutingDecision {
    // Step 1: Filter to capable gateways
    const capable = this.filterCapableGateways(context);
    
    if (capable.length === 0) {
      throw new NoCapableGatewayError(context);
    }
    
    // Step 2: Filter to healthy gateways
    const healthy = capable.filter(g => 
      this.gatewayHealth.get(g)?.isHealthy() ?? true
    );
    
    if (healthy.length === 0) {
      // All gateways unhealthy - try primary anyway
      return {
        primaryGateway: capable[0],
        fallbackGateways: capable.slice(1),
        reason: 'all_gateways_degraded',
      };
    }
    
    // Step 3: Apply routing rules
    const ruleResult = this.applyRoutingRules(healthy, context);
    if (ruleResult) {
      return ruleResult;
    }
    
    // Step 4: Cost-optimized or success-rate-optimized selection
    const ranked = this.rankGateways(healthy, context);
    
    return {
      primaryGateway: ranked[0].gateway,
      fallbackGateways: ranked.slice(1).map(r => r.gateway),
      reason: ranked[0].reason,
    };
  }
  
  private filterCapableGateways(context: RoutingContext): string[] {
    const capable: string[] = [];
    
    for (const [name, gateway] of this.gateways) {
      // Check payment method support
      if (!gateway.supportedMethods.includes(context.paymentMethod)) {
        continue;
      }
      
      // Check currency support
      if (!gateway.supportedCurrencies.includes(context.currency)) {
        continue;
      }
      
      capable.push(name);
    }
    
    return capable;
  }
  
  private applyRoutingRules(
    gateways: string[],
    context: RoutingContext
  ): RoutingDecision | null {
    for (const rule of this.routingRules) {
      if (this.ruleMatches(rule, context)) {
        const targetGateway = rule.targetGateway;
        
        if (gateways.includes(targetGateway)) {
          return {
            primaryGateway: targetGateway,
            fallbackGateways: gateways.filter(g => g !== targetGateway),
            reason: `rule:${rule.name}`,
          };
        }
      }
    }
    return null;
  }
  
  private rankGateways(
    gateways: string[],
    context: RoutingContext
  ): Array<{ gateway: string; score: number; reason: string }> {
    return gateways
      .map(gateway => {
        const successRate = this.getSuccessRate(gateway, context);
        const cost = this.estimateCost(gateway, context);
        
        // Weighted score: 70% success rate, 30% cost optimization
        const score = (successRate * 0.7) + ((1 - cost) * 0.3);
        
        return { gateway, score, reason: `score:${score.toFixed(2)}` };
      })
      .sort((a, b) => b.score - a.score);
  }
  
  private getSuccessRate(
    gateway: string,
    context: RoutingContext
  ): number {
    // Get historical success rate for this gateway + context
    // Segment by: card network, issuing country, MCC
    const key = `${gateway}:${context.cardNetwork}:${context.cardCountry}`;
    return this.successRates.get(key)?.rate ?? 0.95;
  }
  
  private estimateCost(
    gateway: string,
    context: RoutingContext
  ): number {
    // Normalized cost (0-1) based on gateway fees + interchange
    // Lower is better
    const baseFees: Record<string, number> = {
      'stripe': 0.029,
      'adyen': 0.025,
      'braintree': 0.0259,
    };
    return baseFees[gateway] ?? 0.03;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

interface PaymentMethodToken {
  id: string;                    // Your internal ID
  gatewayToken: string;          // Gateway's token reference
  gateway: string;               // Which gateway issued this token
  customerId: string;            // Token owner
  
  // Card metadata (non-sensitive)
  cardBrand: CardBrand;
  last4: string;
  expiryMonth: number;
  expiryYear: number;
  fingerprint: string;           // For duplicate detection
  
  // Network tokenization (if available)
  networkToken?: {
    type: 'visa' | 'mastercard';
    tokenReferenceId: string;
  };
  
  // State
  isDefault: boolean;
  createdAt: Date;
  lastUsedAt: Date;
}
 
class TokenizationService {
  constructor(
    private gateways: GatewayFactory,
    private tokenRepository: TokenRepository
  ) {}
  
  /**
   * Store a new payment method for a customer
   */
  async tokenize(
    customerId: string,
    gatewayToken: string,
    gateway: string
  ): Promise<PaymentMethodToken> {
    // Get card metadata from gateway
    const gatewayClient = this.gateways.getGateway(gateway);
    const cardDetails = await gatewayClient.getPaymentMethodDetails(gatewayToken);
    
    // Check for duplicates using card fingerprint
    const existing = await this.tokenRepository.findByFingerprint(
      customerId,
      cardDetails.fingerprint
    );
    
    if (existing) {
      // Update existing token instead of creating duplicate
      return this.updateToken(existing.id, gatewayToken);
    }
    
    // Create new token record
    const token: PaymentMethodToken = {
      id: generateUuid(),
      gatewayToken,
      gateway,
      customerId,
      cardBrand: cardDetails.brand,
      last4: cardDetails.last4,
      expiryMonth: cardDetails.expMonth,
      expiryYear: cardDetails.expYear,
      fingerprint: cardDetails.fingerprint,
      isDefault: await this.isFirstPaymentMethod(customerId),
      createdAt: new Date(),
      lastUsedAt: new Date(),
    };
    
    await this.tokenRepository.save(token);
    return token;
  }
  
  /**
   * Retrieve token for payment processing
   */
  async getToken(
    tokenId: string,
    customerId: string
  ): Promise<PaymentMethodToken> {
    const token = await this.tokenRepository.findById(tokenId);
    
    if (!token) {
      throw new PaymentMethodNotFoundError(tokenId);
    }
    
    // Security: Verify token belongs to customer
    if (token.customerId !== customerId) {
      throw new UnauthorizedPaymentMethodError();
    }
    
    // Check if token is expired
    if (this.isTokenExpired(token)) {
      throw new PaymentMethodExpiredError(token);
    }
    
    return token;
  }
  
  /**
   * Handle card expiration - called by Account Updater webhook
   */
  async handleCardUpdate(
    oldFingerprint: string,
    newCardDetails: CardUpdateDetails
  ): Promise<void> {
    const tokens = await this.tokenRepository.findAllByFingerprint(
      oldFingerprint
    );
    
    for (const token of tokens) {
      // Request new token from gateway
      const gatewayClient = this.gateways.getGateway(token.gateway);
      const newToken = await gatewayClient.updatePaymentMethod(
        token.gatewayToken,
        newCardDetails
      );
      
      await this.tokenRepository.update(token.id, {
        gatewayToken: newToken,
        expiryMonth: newCardDetails.expMonth,
        expiryYear: newCardDetails.expYear,
      });
    }
  }
  
  private isTokenExpired(token: PaymentMethodToken): boolean {
    const now = new Date();
    const expiry = new Date(token.expiryYear, token.expiryMonth - 1);
    return now > expiry;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

enum CircuitState {
  CLOSED,      // Normal operation, requests flow through
  OPEN,        // Gateway failed, reject requests immediately
  HALF_OPEN,   // Testing if gateway recovered
}
 
interface CircuitBreakerConfig {
  failureThreshold: number;      // Failures before opening (e.g., 5)
  successThreshold: number;      // Successes to close again (e.g., 3)
  timeout: number;               // Time in OPEN before trying again (e.g., 30000ms)
  volumeThreshold: number;       // Min requests before evaluating (e.g., 10)
  errorPercentageThreshold: number; // e.g., 50 = 50% failure rate
}
 
class CircuitBreaker {
  private state: CircuitState = CircuitState.CLOSED;
  private failureCount = 0;
  private successCount = 0;
  private lastFailureTime: number = 0;
  private requestCount = 0;
  
  constructor(
    private readonly name: string,
    private readonly config: CircuitBreakerConfig,
    private readonly metrics: MetricsClient
  ) {}
  
  isHealthy(): boolean {
    return this.state !== CircuitState.OPEN;
  }
  
  async execute<T>(operation: () => Promise<T>): Promise<T> {
    // Check if circuit should transition from OPEN to HALF_OPEN
    if (this.state === CircuitState.OPEN) {
      if (Date.now() - this.lastFailureTime > this.config.timeout) {
        this.transition(CircuitState.HALF_OPEN);
      } else {
        throw new CircuitOpenError(this.name);
      }
    }
    
    this.requestCount++;
    
    try {
      const result = await operation();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure(error);
      throw error;
    }
  }
  
  private onSuccess(): void {
    this.failureCount = 0;
    
    if (this.state === CircuitState.HALF_OPEN) {
      this.successCount++;
      
      if (this.successCount >= this.config.successThreshold) {
        this.transition(CircuitState.CLOSED);
      }
    }
    
    this.metrics.increment('circuit_breaker.success', { gateway: this.name });
  }
  
  private onFailure(error: unknown): void {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    
    // Only count certain errors as failures
    if (!this.isCircuitBreakerError(error)) {
      return;
    }
    
    this.metrics.increment('circuit_breaker.failure', { gateway: this.name });
    
    if (this.state === CircuitState.HALF_OPEN) {
      // Any failure in half-open goes back to open
      this.transition(CircuitState.OPEN);
      return;
    }
    
    // Check if we should open the circuit
    if (this.requestCount >= this.config.volumeThreshold) {
      const failureRate = this.failureCount / this.requestCount;
      
      if (failureRate >= this.config.errorPercentageThreshold / 100) {
        this.transition(CircuitState.OPEN);
      }
    }
  }
  
  private transition(newState: CircuitState): void {
    const oldState = this.state;
    this.state = newState;
    
    if (newState === CircuitState.CLOSED) {
      this.resetCounts();
    }
    
    if (newState === CircuitState.HALF_OPEN) {
      this.successCount = 0;
    }
    
    this.metrics.gauge('circuit_breaker.state', newState, { 
      gateway: this.name 
    });
    
    console.log(`Circuit breaker [${this.name}]: ${oldState} -> ${newState}`);
  }
  
  private isCircuitBreakerError(error: unknown): boolean {
    // Don't trip circuit for business errors (declines, validation)
    if (error instanceof CardDeclinedError) return false;
    if (error instanceof ValidationError) return false;
    
    // Trip circuit for infrastructure errors
    if (error instanceof TimeoutError) return true;
    if (error instanceof NetworkError) return true;
    if (error instanceof GatewayUnavailableError) return true;
    
    return true; // Default to counting as failure
  }
  
  private resetCounts(): void {
    this.failureCount = 0;
    this.successCount = 0;
    this.requestCount = 0;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

class ResilientPaymentService {
  private gatewayBreakers: Map<string, CircuitBreaker>;
  private router: GatewayRouter;
  
  async processPayment(
    request: PaymentRequest
  ): Promise<PaymentResult> {
    const routingDecision = this.router.selectGateway({
      amount: request.amount,
      currency: request.currency,
      paymentMethod: request.paymentMethodType,
      // ... other context
    });
    
    const gatewaysToTry = [
      routingDecision.primaryGateway,
      ...routingDecision.fallbackGateways,
    ];
    
    let lastError: Error | null = null;
    
    for (const gatewayName of gatewaysToTry) {
      const breaker = this.gatewayBreakers.get(gatewayName)!;
      
      if (!breaker.isHealthy()) {
        // Skip unhealthy gateways unless it's our last option
        if (gatewaysToTry.indexOf(gatewayName) < gatewaysToTry.length - 1) {
          continue;
        }
      }
      
      try {
        const result = await breaker.execute(async () => {
          const gateway = this.getGateway(gatewayName);
          return gateway.authorize({
            ...request,
            idempotencyKey: `${request.idempotencyKey}:${gatewayName}`,
          });
        });
        
        // Success! Record which gateway was used
        return {
          ...result,
          gatewayUsed: gatewayName,
          failoverAttempts: gatewaysToTry.indexOf(gatewayName),
        };
        
      } catch (error) {
        lastError = error as Error;
        
        // Don't failover on business errors (card declined)
        if (error instanceof CardDeclinedError) {
          throw error;
        }
        
        // Log failover attempt
        this.metrics.increment('payment.failover', {
          from: gatewayName,
          error: error.name,
        });
        
        // Continue to next gateway
      }
    }
    
    // All gateways failed
    throw new AllGatewaysFailedError(gatewaysToTry, lastError);
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

// Error classification for retry/failover decisions
 
enum ErrorCategory {
  HARD_DECLINE,         // Don't retry, don't failover
  SOFT_DECLINE,         // Retry later with same gateway
  VALIDATION_ERROR,     // Fix input, don't retry
  REQUIRES_ACTION,      // Customer action needed
  GATEWAY_ERROR,        // Retry immediately with failover
  NETWORK_ERROR,        // Retry with backoff and failover
  RATE_LIMITED,         // Retry after delay
}
 
interface ClassifiedError {
  category: ErrorCategory;
  code: string;
  message: string;
  retryable: boolean;
  retryAfterMs?: number;
  failoverAllowed: boolean;
  userMessage: string;
}
 
class GatewayErrorClassifier {
  // Map gateway-specific error codes to our categories
  private stripeDeclineCodes: Record<string, ErrorCategory> = {
    'insufficient_funds': ErrorCategory.SOFT_DECLINE,
    'card_velocity_exceeded': ErrorCategory.SOFT_DECLINE,
    'do_not_honor': ErrorCategory.HARD_DECLINE,
    'stolen_card': ErrorCategory.HARD_DECLINE,
    'fraudulent': ErrorCategory.HARD_DECLINE,
    'generic_decline': ErrorCategory.HARD_DECLINE,
    'processing_error': ErrorCategory.GATEWAY_ERROR,
  };
  
  classify(gateway: string, error: GatewayError): ClassifiedError {
    // Network-level errors
    if (error instanceof TimeoutError) {
      return {
        category: ErrorCategory.NETWORK_ERROR,
        code: 'timeout',
        message: 'Gateway request timed out',
        retryable: true,
        retryAfterMs: 1000,
        failoverAllowed: true,
        userMessage: 'Payment is being processed. Please wait.',
      };
    }
    
    if (error instanceof RateLimitError) {
      return {
        category: ErrorCategory.RATE_LIMITED,
        code: 'rate_limited',
        message: 'Gateway rate limit exceeded',
        retryable: true,
        retryAfterMs: error.retryAfter * 1000,
        failoverAllowed: true,
        userMessage: 'Too many payment attempts. Please try again shortly.',
      };
    }
    
    // Stripe-specific classification
    if (gateway === 'stripe' && error instanceof StripeCardError) {
      const category = this.stripeDeclineCodes[error.decline_code] 
        ?? ErrorCategory.HARD_DECLINE;
      
      return {
        category,
        code: error.decline_code,
        message: error.message,
        retryable: category === ErrorCategory.SOFT_DECLINE,
        retryAfterMs: category === ErrorCategory.SOFT_DECLINE ? 300000 : undefined, // 5 min
        failoverAllowed: false,
        userMessage: this.getUserMessage(category, error.decline_code),
      };
    }
    
    // Default to gateway error (retryable with failover)
    return {
      category: ErrorCategory.GATEWAY_ERROR,
      code: 'unknown',
      message: error.message,
      retryable: true,
      failoverAllowed: true,
      userMessage: 'Something went wrong. Please try again.',
    };
  }
  
  private getUserMessage(category: ErrorCategory, code: string): string {
    const messages: Record<string, string> = {
      'insufficient_funds': 'Card has insufficient funds. Please try another card.',
      'card_velocity_exceeded': 'Too many transactions. Please wait a few minutes.',
      'do_not_honor': 'Card was declined. Please contact your bank.',
      'stolen_card': 'Card was declined. Please use a different card.',
      'expired_card': 'Card has expired. Please update your card details.',
    };
    
    return messages[code] ?? 'Payment was declined. Please try a different payment method.';
  }
}