Stripe订阅模式Checkout结账页如何正确采集收货地址

搭建提供实物配送到家服务的在线订阅业务时，结账流程目前仅能正常采集用户姓名、邮编与支付信息，无法引导用户填写完整收货地址，需要排查配置问题并给出调整方案。

现有前端跳转代码 #

import {loadStripe} from '@stripe/stripe-js'

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_API_KEY)

export async function initiateCheckout({lineItems} = {}) {
  const stripe = await stripePromise
  await stripe.redirectToCheckout({
    mode: 'subscription',
    lineItems,
    successUrl: `${window.location.origin}?session_id={CHECKOUT_SESSION_ID}`,
    cancelUrl: `${window.location.origin}/microgreens`,
  })
}

触发的报错信息 #

Uncaught (in promise) IntegrationError: Invalid stripe.redirectToCheckout parameter: shipping_address_collection is not an accepted parameter.

当前结账页效果 #

报错的核心原因是配置位置错误：shipping_address_collection 不属于前端 stripe.redirectToCheckout 方法支持的入参，Stripe 明确要求所有涉及结账规则、信息采集范围的配置，必须在服务端创建 Checkout Session 时设置，前端跳转方法仅支持传入已经生成好的 Session ID 完成跳转，不支持直接在前端声明这类配置。

按以下步骤修改即可在订阅模式结账页正常采集完整收货地址：

• 移除前端跳转逻辑中所有尝试直接传入的收货地址、配送规则类参数，前端不再直接拼接全量结账配置，改为先请求自有服务端接口生成 Checkout Session。
• 在服务端创建 Stripe Checkout Session 的逻辑中，新增收货地址采集配置，Node.js 环境示例代码如下：

// 服务端 /api/create-checkout-session 接口逻辑
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

export default async function handler(req, res) {
  const {lineItems} = req.body;
  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    lineItems,
    successUrl: `${process.env.NEXT_PUBLIC_SITE_URL}?session_id={CHECKOUT_SESSION_ID}`,
    cancelUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/microgreens`,
    // 新增收货地址采集配置
    shipping_address_collection: {
      allowed_countries: ['CN'], // 替换为你实际支持配送的国家/地区二位编码，可添加多个
    },
    // 若需要设置配送运费规则，可额外配置shipping_options参数
  });
  res.status(200).json({sessionId: session.id});
}

• 调整前端跳转逻辑，先调用服务端接口拿到 Session ID 后再完成跳转，修改后的前端代码如下：

import {loadStripe} from '@stripe/stripe-js'

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_API_KEY)

export async function initiateCheckout({lineItems} = {}) {
  const stripe = await stripePromise
  // 请求自有服务端接口创建Checkout Session
  const resp = await fetch('/api/create-checkout-session', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({lineItems})
  })
  const {sessionId} = await resp.json()
  // 仅传入sessionId完成跳转，不要在前端加其他结账规则配置
  await stripe.redirectToCheckout({
    sessionId
  })
}

补充说明：订阅模式下Stripe Checkout默认仅采集支付履约必需的最少信息，地址类、税务类、配送规则类配置均不支持在前端设置，必须在服务端创建Session时声明，否则不仅会触发参数错误，也会带来配置被恶意篡改的安全风险。

内容的提问来源于stack exchange，提问作者Tyler Morales