如何让Stripe Checkout计算包含运费和税费的总计金额？

背景 #

基于React、Next.js、Prisma DB构建的电商店铺，支持向管理后台传输数据，通过Stripe Checkout处理支付流程。

问题 #

当前Stripe Checkout页面仅展示购物车商品的总价，未将shippingCost（运费）和stateTax（州税）计入订单总计。

需求 #

在Stripe Checkout页面展示商品总价 + 运费 + 州税的订单总计金额。

疑问 #

若问题根源在于line_items配置，该如何调整以显示正确的总计金额？

相关代码片段 #

products.forEach((product) => {
line_items.push({
  quantity: 1,
  price_data: {
    currency: 'USD',
    product_data: {
      name: product.name,
    },
    unit_amount: product.price.toNumber() * 100,
  }
});
});

const order = await prismadb.order.create({
data: {
  storeId: params.storeId,
  isPaid: false,
  orderItems: {
    create: orderItems.productIds.map((productId: string) => ({
      product: {
        connect: {
          id: productId
        }
      },
      shippingType: orderItems.shippingType,
      shippingCost: orderItems.shippingCost.toString(),
      stateTax: orderItems.stateTax.toString(),
    }))
  }
}
});

解决方案 #

方案1：直接在line_items中添加运费和税费条目 #

在生成商品条目后，将运费和州税作为单独的line item追加到数组中，Stripe会自动累加所有条目金额作为总计：

// 生成商品条目
products.forEach((product) => {
  line_items.push({
    quantity: 1,
    price_data: {
      currency: 'USD',
      product_data: {
        name: product.name,
      },
      unit_amount: product.price.toNumber() * 100,
    }
  });
});

// 添加运费条目（仅当运费大于0时）
if (orderItems.shippingCost > 0) {
  line_items.push({
    quantity: 1,
    price_data: {
      currency: 'USD',
      product_data: {
        name: `${orderItems.shippingType} 运费`,
      },
      unit_amount: Math.round(orderItems.shippingCost * 100), // 转换为Stripe要求的分单位
    }
  });
}

// 添加州税条目（仅当税费大于0时）
if (orderItems.stateTax > 0) {
  line_items.push({
    quantity: 1,
    price_data: {
      currency: 'USD',
      product_data: {
        name: '州税',
      },
      unit_amount: Math.round(orderItems.stateTax * 100), // 转换为分单位
    }
  });
}

方案2：使用Stripe官方推荐的Tax Rates + Shipping Options（更合规） #

如果需要更专业的税费和运费管理，建议使用Stripe原生的税率和配送选项功能：

1. 在Stripe后台创建对应州的税率，获取其ID
2. 构建配送选项并关联到Checkout Session：

// 替换为你在Stripe后台创建的州税Rate ID
const stateTaxRateId = 'your-state-tax-rate-id';

// 构建配送选项
const shippingOptions = [
  {
    shipping_rate_data: {
      type: 'fixed_amount',
      fixed_amount: {
        amount: Math.round(orderItems.shippingCost * 100),
        currency: 'USD',
      },
      display_name: orderItems.shippingType,
      delivery_estimate: {
        minimum: { unit: 'business_day', value: 2 },
        maximum: { unit: 'business_day', value: 5 },
      },
    },
  },
];

// 创建Stripe Checkout Session时传入配置
const session = await stripe.checkout.sessions.create({
  payment_method_types: ['card'],
  line_items: line_items,
  mode: 'payment',
  success_url: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
  cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/cart`,
  tax_rates: [stateTaxRateId], // 关联州税
  shipping_options: shippingOptions, // 添加配送选项
});

关键注意事项 #

• Stripe金额单位为分，所有金额必须乘以100并取整，避免小数精度错误
• 确保orderItems.shippingCost和orderItems.stateTax为数值类型，若当前是字符串需先转换为数字
• 方案2中，税费会自动计算到商品总价，无需手动添加到line_items；运费会作为单独选项展示在Checkout页面

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