NextJS中调用Stripe API时billingPortal函数不存在的问题

核心原因 #

你当前使用的@stripe/stripe-js（前端Stripe SDK）不支持billingPortal相关API——这个接口属于Stripe后端专属能力，必须通过Node.js后端SDK调用，前端实例没有对应的方法，所以会出现Cannot read properties of undefined (reading 'sessions')错误。

解决方案：前后端分离实现 #

1. 后端创建API路由（处理Portal Session生成）

在NextJS项目中新建API路由文件（如pages/api/create-portal-session.ts），使用Stripe Node.js SDK完成会话创建：

import type { NextApiRequest, NextApiResponse } from 'next';
import Stripe from 'stripe';

// 初始化后端Stripe实例（使用Secret Key，切勿暴露到前端）
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-06-20', // 匹配你Stripe后台的API版本
});

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // 仅允许POST请求
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const { customerId } = req.body;

  try {
    // 调用Stripe后端API生成客户门户会话
    const session = await stripe.billingPortal.sessions.create({
      customer: customerId,
      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/account`,
    });

    return res.status(200).json({ url: session.url });
  } catch (error) {
    return res.status(500).json({ error: (error as Error).message });
  }
}

2. 前端调用API路由获取跳转链接

前端不再直接操作stripeJS.billingPortal，改为请求上面的API接口获取门户链接：

const handleOpenCustomerPortal = async () => {
  try {
    const response = await fetch('/api/create-portal-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ customerId: 'your_customer_id' }), // 替换为实际客户ID
    });

    const data = await response.json();
    if (data.url) {
      window.location.href = data.url; // 跳转到客户门户
    }
  } catch (error) {
    console.error('生成客户门户失败:', error);
  }
};

关键注意事项 #

• 后端必须使用Stripe Secret Key，绝对不能在前端代码中暴露该密钥。
• 前端的getStripeJs()返回的实例仅用于前端支付流程（如加载Elements、确认支付），不支持后端专属API。
• 确保Stripe Node.js SDK版本与你Stripe后台配置的API版本一致，避免兼容性问题。

内容的提问来源于stack exchange，提问作者engineer-x