{
  "error": {
    "code": "bad_request",
    "message": "Promotion code 'EXPIRED123' is not valid: Code has expired"
  }
}

// 處理優惠碼錯誤
const res = await fetch('https://api.recur.tw/v1/checkout/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.RECUR_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    productId: 'prod_xxx',
    promotionCode: userInputCode,
    successUrl: 'https://your-site.com/success',
    cancelUrl: 'https://your-site.com/cancel',
  }),
});

if (res.status === 400) {
  const { error } = await res.json();
  // 向用戶顯示錯誤訊息
  showError(error.message); // 例如 "Promotion code 'XXX' is not valid: Code has expired"
  // 可以讓用戶重新輸入優惠碼，或不帶優惠碼重新建立 Session
}

await checkout({
  productId: 'prod_xxx',
  customerEmail: 'user@example.com',
  onError: (error) => {
    if (error.code === 'conflict') {
      // 客戶已有該商品的有效訂閱
      const details = error.details?.[0];
      if (details?.existing_subscription_id) {
        console.log('現有訂閱 ID:', details.existing_subscription_id);
        console.log('訂閱狀態:', details.status);

        // 引導用戶到 Customer Portal 管理訂閱
        window.location.href = '/account/subscriptions';
      }
    }
  },
});

await checkout({
  productId: 'prod_xxx',
  onPaymentFailed: (error) => {
    console.log('付款失敗:', {
      code: error.details?.failure_code,
      message: error.details?.failure_message,
      canRetry: error.details?.can_retry,
    });

    // 回傳 undefined 使用 SDK 預設行為
  },
});

await checkout({
  productId: 'prod_xxx',
  onPaymentFailed: (error) => {
    const failureCode = error.details?.failure_code;

    // 餘額不足 - 顯示自訂訊息
    if (failureCode === 'INSUFFICIENT_FUNDS') {
      return {
        action: 'custom',
        customTitle: '餘額不足',
        customMessage: '您的卡片餘額不足，請使用其他付款方式或聯繫銀行。',
      };
    }

    // 卡片過期 - 關閉結帳視窗
    if (failureCode === 'EXPIRED_CARD') {
      return { action: 'close' };
    }

    // 其他錯誤 - 使用預設行為（允許重試）
    return undefined;
  },
});

// 允許重試（預設）
return { action: 'retry' };

// 關閉視窗
return { action: 'close' };

// 自訂訊息
return {
  action: 'custom',
  customTitle: '付款失敗',
  customMessage: '請聯繫客服取得協助',
};

const recur = RecurCheckout.init({
  publishableKey: 'pk_test_xxx',
});

document.getElementById('subscribe-btn').addEventListener('click', async () => {
  await recur.checkout({
    productId: 'prod_xxx',
    mode: 'modal',
    onPaymentFailed: (error) => {
      console.log('付款失敗:', error);

      // 根據錯誤碼處理
      switch (error.details?.failure_code) {
        case 'INSUFFICIENT_FUNDS':
          return {
            action: 'custom',
            customTitle: '餘額不足',
            customMessage: '請確認卡片餘額或使用其他卡片。',
          };

        case 'NETWORK_ERROR':
        case 'TIMEOUT':
          // 網路問題 - 允許重試
          return { action: 'retry' };

        default:
          // 使用 SDK 預設行為
          return undefined;
      }
    },
    onPaymentComplete: (result) => {
      window.location.href = '/success';
    },
    onError: (error) => {
      alert('發生錯誤：' + error.message);
    },
  });
});

interface CheckoutError {
  /** 錯誤代碼（如 'conflict', 'not_found', 'payment_required'） */
  code: string;
  /** 人類可讀的錯誤訊息 */
  message: string;
  /** 相關文件連結（選填） */
  docUrl?: string;
  /** 錯誤詳情（選填） */
  details?: Array<{
    // 付款失敗詳情
    failure_code?: string;    // 付款失敗代碼
    failure_message?: string; // 付款失敗訊息
    can_retry?: boolean;      // 是否可重試
    // 重複訂閱詳情（當 code 為 'conflict'）
    existing_subscription_id?: string;  // 現有訂閱 ID
    status?: string;                     // 現有訂閱狀態
  }>;
}

onPaymentFailed: (error) => {
  if (error.details?.failure_code === 'CARD_DECLINED') {
    return {
      action: 'custom',
      customTitle: '卡片被拒絕',
      customMessage: '您的銀行拒絕了此筆交易。請聯繫發卡銀行或使用其他卡片。',
    };
  }
}

onPaymentFailed: (error) => {
  if (error.details?.can_retry) {
    // 可重試的錯誤 - 讓用戶再試一次
    return { action: 'retry' };
  } else {
    // 不可重試 - 提供替代方案
    return {
      action: 'custom',
      customTitle: '付款失敗',
      customMessage: '請使用其他付款方式或聯繫客服。',
    };
  }
}

onPaymentFailed: (error) => {
  // 記錄到分析服務
  analytics.track('payment_failed', {
    failure_code: error.details?.failure_code,
    failure_message: error.details?.failure_message,
    can_retry: error.details?.can_retry,
  });

  return undefined; // 使用預設行為
}