Payment Error Handling

Decline Code の分類

function classifyCardError(error: Stripe.errors.StripeCardError): PaymentError {
  const declineCode = error.decline_code;

  // 3DS認証が必要
  if (error.code === "authentication_required") {
    return {
      category: "authentication_required",
      code: error.code,
      message: error.message,
      userMessage: "カードの追加認証が必要です。認証を完了してください。",
      retryable: false, // 3DSフロー経由で再試行
      declineCode,
    };
  }

  // カード拒否の分類
  const declineInfo = getDeclineInfo(declineCode);

  return {
    category: "card_declined",
    code: error.code ?? "card_declined",
    message: error.message,
    userMessage: declineInfo.userMessage,
    retryable: declineInfo.retryable,
    declineCode,
  };
}

interface DeclineInfo {
  userMessage: string;
  retryable: boolean;
}

function getDeclineInfo(declineCode: string | undefined): DeclineInfo {
  switch (declineCode) {
    // リトライ可能な一時的拒否
    case "insufficient_funds":
      return {
        userMessage: "カードの残高が不足しています。別のカードをお試しください。",
        retryable: true,
      };
    case "processing_error":
      return {
        userMessage: "決済処理中にエラーが発生しました。再度お試しください。",
        retryable: true,
      };
    case "try_again_later":
      return {
        userMessage: "一時的にカードが使用できません。しばらく後に再度お試しください。",
        retryable: true,
      };

    // リトライ不可能な永続的拒否
    case "card_not_supported":
      return {
        userMessage: "このカードはサポートされていません。別のカードをお使いください。",
        retryable: false,
      };
    case "expired_card":
      return {
        userMessage: "カードの有効期限が切れています。別のカードをお使いください。",
        retryable: false,
      };
    case "incorrect_cvc":
      return {
        userMessage: "セキュリティコード（CVC）が正しくありません。確認の上、再度お試しください。",
        retryable: true,
      };
    case "incorrect_number":
      return {
        userMessage: "カード番号が正しくありません。確認の上、再度お試しください。",
        retryable: true,
      };
    case "stolen_card":
    case "lost_card":
    case "merchant_blacklist":
      return {
        userMessage: "このカードは使用できません。カード会社にお問い合わせください。",
        retryable: false,
      };
    case "do_not_honor":
      return {
        userMessage: "カード会社により決済が拒否されました。カード会社にお問い合わせいただくか、別のカードをお試しください。",
        retryable: false,
      };

    // 不正検知
    case "fraudulent":
      return {
        userMessage: "決済が拒否されました。別のカードをお試しください。",
        retryable: false,
      };

    default:
      return {
        userMessage: "カード決済が拒否されました。別のカードをお試しいただくか、カード会社にお問い合わせください。",
        retryable: false,
      };
  }
}

3D Secure ハンドリング

// サーバー側: PaymentIntent確認時の3DS対応
async function confirmPayment(
  paymentIntentId: string,
): Promise<{ status: string; clientSecret?: string; redirectUrl?: string }> {
  try {
    const paymentIntent = await stripe.paymentIntents.confirm(paymentIntentId);

    if (paymentIntent.status === "requires_action") {
      // 3DS認証が必要
      return {
        status: "requires_action",
        clientSecret: paymentIntent.client_secret!,
      };
    }

    if (paymentIntent.status === "succeeded") {
      return { status: "succeeded" };
    }

    return { status: paymentIntent.status };
  } catch (error) {
    const paymentError = classifyStripeError(error);

    if (paymentError.category === "authentication_required") {
      // PaymentIntentのclient_secretを返してフロントで3DS認証を促す
      const pi = await stripe.paymentIntents.retrieve(paymentIntentId);
      return {
        status: "requires_action",
        clientSecret: pi.client_secret!,
      };
    }

    throw error;
  }
}

// クライアント側: 3DS認証フロー
import { loadStripe } from "@stripe/stripe-js";

const stripeClient = await loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

async function handle3DSAuthentication(clientSecret: string): Promise<{
  success: boolean;
  error?: string;
}> {
  if (!stripeClient) {
    return { success: false, error: "Stripe not loaded" };
  }

  const { error, paymentIntent } = await stripeClient.confirmCardPayment(
    clientSecret,
  );

  if (error) {
    return {
      success: false,
      error: error.message ?? "認証に失敗しました",
    };
  }

  if (paymentIntent?.status === "succeeded") {
    return { success: true };
  }

  return { success: false, error: "決済が完了しませんでした" };
}

リトライ戦略

interface RetryConfig {
  maxAttempts: number;
  baseDelayMs: number;
  maxDelayMs: number;
}

const DEFAULT_RETRY_CONFIG: RetryConfig = {
  maxAttempts: 3,
  baseDelayMs: 1000,
  maxDelayMs: 10_000,
};

async function withPaymentRetry<T>(
  operation: () => Promise<T>,
  config: RetryConfig = DEFAULT_RETRY_CONFIG,
): Promise<T> {
  let lastError: PaymentError | undefined;

  for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = classifyStripeError(error);

      // リトライ不可能なエラーは即座にスロー
      if (!lastError.retryable) {
        throw error;
      }

      // 最後の試行なら再スローする
      if (attempt === config.maxAttempts - 1) {
        throw error;
      }

      // 指数バックオフ + ジッター
      const delay = Math.min(
        config.baseDelayMs * Math.pow(2, attempt) + Math.random() * 1000,
        config.maxDelayMs,
      );
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }

  // TypeScript 用: 到達しないが型安全のため
  throw lastError;
}

// 使用例
async function chargeCustomer(customerId: string, amount: number): Promise<Stripe.PaymentIntent> {
  return withPaymentRetry(async () => {
    return stripe.paymentIntents.create({
      customer: customerId,
      amount,
      currency: "jpy",
      confirm: true,
      off_session: true,
    });
  });
}

エラーログとアラート

async function logPaymentError(
  error: PaymentError,
  context: {
    orderId?: string;
    customerId?: string;
    paymentIntentId?: string;
    amount?: number;
  },
): Promise<void> {
  // 構造化ログ
  console.error(JSON.stringify({
    level: "error",
    type: "payment_error",
    category: error.category,
    code: error.code,
    declineCode: error.declineCode,
    retryable: error.retryable,
    message: error.message,
    ...context,
    timestamp: new Date().toISOString(),
  }));

  // DBにエラー記録
  await db.insert(paymentErrors).values({
    category: error.category,
    code: error.code,
    declineCode: error.declineCode,
    orderId: context.orderId,
    customerId: context.customerId,
    paymentIntentId: context.paymentIntentId,
    amount: context.amount,
  });

  // 内部エラーの場合はアラート
  if (error.category === "internal_error" || error.category === "invalid_request") {
    await notifyAlertChannel({
      title: "Payment System Error",
      category: error.category,
      code: error.code,
      message: error.message,
      context,
    });
  }
}

必須ルール

1. StripeErrorを分類してからハンドリングする -- instanceof で型を判定し、適切な対応を選択する
2. ユーザー向けメッセージに内部エラー情報を含めない -- declineの詳細理由はフロード対策上公開しない
3. リトライは冪等な操作のみに適用する -- 冪等キー付きの操作またはGET系のみリトライする
4. 3DS認証はクライアント側で完結させる -- サーバー側ではrequires_action状態を返すだけ
5. authentication_errorはシステムアラートを発火する -- APIキーの漏洩や設定ミスを示す
6. decline codeの統計を取る -- 特定declineの急増はフロード攻撃の兆候
7. fraudulentの詳細をユーザーに返さない -- 不正検知の仕組みが推測されるリスク

アンチパターン

• 全Stripeエラーを同一のcatchブロックで処理する（エラー種別ごとに対応が異なる）
• decline_codeをそのままユーザーに表示する（技術用語は理解できず、セキュリティリスクもある）
• card_errorに対してサーバー側でリトライする（同じカードで同じ結果になる）
• 3DS認証をスキップする設定にする（SCA規制違反、チャージバックの免責喪失）
• StripeConnectionErrorでリトライせずエラーを返す（一時的な障害で決済機会を失う）
• エラーレスポンスにStripeのrequest_idを含めずログに記録する（Stripeサポートへの調査依頼時に必要）

テスト戦略

1. エラー分類テスト: 各StripeError型が正しいPaymentErrorCategoryに分類される
2. Decline Code テスト: 主要なdecline_codeに対して適切なユーザーメッセージが返される
3. リトライテスト: retryable=trueのエラーでリトライされ、falseでは即座にスローされる
4. 3DSフローテスト: requires_action状態でclientSecretが返却される
5. バックオフテスト: リトライ間隔が指数的に増加し、最大値を超えない
6. ログテスト: PaymentErrorの全フィールドが構造化ログに記録される
7. アラートテスト: internal_errorとauthentication_errorでアラートが発火する