本文旨在指导开发者如何在stripe checkout session中正确集成自定义税率和折扣（优惠券/促销码），以实现灵活的定价策略。我们将详细探讨税率和折扣对象的创建、配置及其在checkout session参数中的正确应用方式，并提供完整的代码示例，帮助您避免常见的api错误，确保支付流程的顺畅与准确。
理解Stripe Checkout Session中的税率与折扣机制
在Stripe Checkout Session中集成税率和折扣是构建灵活电商支付流程的关键。Stripe提供了专门的API对象来管理税率和折扣，并允许在创建Checkout Session时引用这些对象。正确理解和使用这些参数对于避免API错误至关重要。
主要涉及的Stripe对象和Checkout Session参数包括：
- Stripe TaxRate 对象: 用于定义具体的税率，如增值税（VAT）、销售税等。
- Stripe Coupon 对象: 用于定义折扣金额或百分比，例如固定金额折扣或百分比折扣。
- Stripe PromotionCode 对象: 提供了比Coupon更灵活的折扣管理，可以设置使用次数限制、有效期等。
- Checkout Session的 tax_rates 参数: 接收一个Stripe TaxRate ID列表，用于将预定义的税率应用于Checkout Session中的商品。
- Checkout Session的 discounts 参数: 接收一个包含Stripe Coupon ID或PromotionCode ID的对象列表，用于将折扣应用于Checkout Session。
创建和管理Stripe税率
在将税率应用于Checkout Session之前，您需要在Stripe中创建相应的TaxRate对象。这些对象可以预先在Stripe Dashboard中创建，也可以通过Stripe API动态创建。
通过API创建Stripe TaxRate
以下代码展示了如何根据订单中的税率信息动态创建TaxRate对象：
import stripe
# 假设 order.tax.all() 返回一个包含税率信息的查询集
# 每个 tax 对象应有 name 和 rate 属性
tax_rates_ids = []
for tax in order.tax.all():
# 检查是否已存在具有相同名称和百分比的税率，避免重复创建
# 实际应用中，您可能需要更复杂的逻辑来管理税率，例如查询现有税率
try:
# 尝试检索现有税率，这里简化处理，直接创建
tax_rate = stripe.TaxRate.create(
display_name=tax.name,
description=f"{tax.name} ({tax.rate}%)",
percentage=tax.rate,
jurisdiction="US", # 根据实际情况设置管辖区
inclusive=False, # 设置税率是否包含在价格中
active=True,
)
tax_rates_ids.append(tax_rate.id)
except stripe.error.StripeError as e:
# 处理错误，例如税率名称重复或参数无效
print(f"创建税率失败: {e}")
# 可以在此处添加重试逻辑或错误日志
pass
参数说明:
- display_name: 在结账页面向客户显示的名称。
- description: 内部描述，可选。
- percentage: 税率百分比，例如 5.0 代表 5%。
- jurisdiction: 税率适用的管辖区，例如 "US", "RU"。
- inclusive: 布尔值，如果为 True，则税率包含在商品价格中；如果为 False，则税率会添加到商品价格之上。
- active: 布率值，表示税率是否激活。
创建和管理Stripe折扣
Stripe支持通过Coupon或PromotionCode对象来应用折扣。Coupon是折扣规则本身，而PromotionCode是Coupon的一个实例，可以用于分发和限制使用。
通过API创建Stripe Coupon
以下代码展示了如何根据订单中的折扣信息动态创建Coupon对象：
import stripe
# 假设 order.discount.all() 返回一个包含折扣信息的查询集
# 每个 discount 对象应有 name 和 amount 属性
discount_coupon_ids = []
for discount in order.discount.all():
try:
# 实际应用中，您可能需要查询现有优惠券，或生成唯一的ID
coupon = stripe.Coupon.create(
amount_off=discount.amount * 100, # 金额以最小货币单位（例如美分）表示
duration='once', # 'once', 'forever', or 'repeating'
currency='usd', # 优惠券适用的货币
name=discount.name,
)
discount_coupon_ids.append(coupon.id)
except stripe.error.StripeError as e:
print(f"创建优惠券失败: {e}")
pass
参数说明:
- amount_off: 固定金额折扣（以最小货币单位表示），与 percent_off 二选一。
- percent_off: 百分比折扣（0-100），与 amount_off 二选一。
- duration: 优惠券的持续时间 (once, forever, repeating)。
- currency: 优惠券适用的货币。
- name: 优惠券的名称。
集成税率与折扣到Checkout Session
在创建Stripe Checkout Session时，通过tax_rates和discounts参数引用已创建的税率和折扣对象ID。这是将这些规则应用于用户订单的关键步骤。
正确的参数结构
- tax_rates: 期望一个字符串列表，每个字符串是Stripe TaxRate的ID。 tax_rates=['tax_rate_id_1', 'tax_rate_id_2']
- discounts: 期望一个字典列表，每个字典包含一个coupon或promotion_code键，其值为对应的ID。 discounts=[{'coupon': 'coupon_id_here'}] 或 discounts=[{'promotion_code': 'promo_code_id_here'}]
完整示例代码
以下是一个修正后的Django视图代码，演示了如何正确地将动态创建的税率和优惠券集成到Stripe Checkout Session中：
import stripe
from django.views import View
from django.http import JsonResponse
from .models import Order # 假设您有一个Order模型
# 确保Stripe API密钥已配置
# stripe.api_key = 'YOUR_STRIPE_SECRET_KEY'
class CreateCheckoutSessionOrderView(View):
def get(self, request, *args, **kwargs):
order_id = self.kwargs["order_id"]
DOMAIN: str = 'http://127.0.0.1:8000' # 您的域名
order = Order.objects.get(id=order_id)
# 1. 处理税率
tax_rates_ids = []
for tax in order.tax.all():
try:
# 实际应用中，您可能需要先查询Stripe是否存在同名/同百分比的TaxRate
# 这里为了演示，每次都尝试创建。生产环境建议复用已存在的TaxRate。
tax_rate = stripe.TaxRate.create(
display_name=tax.name,
description=f"{tax.name} ({tax.rate}%)",
percentage=tax.rate,
jurisdiction="US", # 根据您的业务逻辑设置
inclusive=False, # 根据您的业务逻辑设置
active=True,
)
tax_rates_ids.append(tax_rate.id)
except stripe.error.StripeError as e:
print(f"创建税率失败: {e}")
# 可以在此处添加更详细的错误处理或日志记录
# 如果税率创建失败，可能需要中断流程或跳过此税率
pass
# 2. 处理折扣 (使用优惠券)
# 注意: 这里的discounts列表结构是Stripe API要求的
# 每个字典应包含 'coupon' 或 'promotion_code' 键
discounts_list_for_session = []
for discount in order.discount.all():
try:
# 实际应用中，您可能需要先查询Stripe是否存在同名/同金额的Coupon
# 生产环境建议复用已存在的Coupon或PromotionCode
coupon = stripe.Coupon.create(
amount_off=int(discount.amount * 100), # Stripe金额以最小货币单位（例如美分）表示
duration='once',
currency='usd',
name=discount.name,
)
discounts_list_for_session.append({'coupon': coupon.id})
except stripe.error.StripeError as e:
print(f"创建优惠券失败: {e}")
pass
# 3. 创建Checkout Session
try:
session = stripe.checkout.Session.create(
payment_method_types=['card'],
line_items=[
{
'price_data': {
'currency': 'usd',
'unit_amount': int(order.get_total_cost() * 100), # 确保金额是整数，以最小货币单位表示
'product_data': {
'name': order.__str__(),
},
},
'quantity': 1,
},
],
payment_intent_data={
'metadata': {
'order_id': str(order.id), # 确保metadata中的值是字符串
},
},
mode='payment',
success_url=DOMAIN + '/success/',
cancel_url=DOMAIN + '/cancel/',
tax_rates=tax_rates_ids, # 正确传递税率ID列表
discounts=discounts_list_for_session, # 正确传递折扣列表
)
return JsonResponse({'id': session.id})
except stripe.error.StripeError as e:
# 捕获Stripe API错误
print(f"创建Checkout Session失败: {e}")
return JsonResponse({'error': str(e)}, status=500)
except Exception as e:
# 捕获其他未知错误
print(f"发生未知错误: {e}")
return JsonResponse({'error': 'An unexpected error occurred'}, status=500)
注意事项
- Stripe API密钥管理: 确保您的Stripe API密钥（stripe.api_key）已正确配置，并且在生产环境中使用秘密密钥。
- 金额单位: Stripe API要求所有金额（unit_amount, amount_off等）都以最小货币单位表示（例如，美元使用美分，欧元使用欧分）。因此，在传递金额时，请务必将其乘以100并转换为整数。
- 税率和优惠券的生命周期: 在生产环境中，频繁地创建新的TaxRate和Coupon对象可能不是最佳实践。通常，您会预先在Stripe Dashboard或通过API创建这些对象，然后在代码中通过其ID引用它们。只有当税率或折扣规则频繁变化且无法预设时，才考虑动态创建。
- 错误处理: 在与Stripe API交互时，务必添加健壮的错误处理机制，捕获stripe.error.StripeError及其子类，以便优雅地处理API调用失败的情况。
- 自动税收 (Automatic Tax): Stripe还提供了自动税收功能 (automatic_tax={'enabled': True})，可以根据客户的地理位置和产品类型自动计算税费。如果您的业务场景需要复杂的全球税收合规，可以考虑使用此功能，它会替代手动传递tax_rates。
- 测试: 在Stripe的测试模式下充分测试您的集成，确保税率和折扣的计算和应用符合预期。
- 数据类型: metadata中的值必须是字符串类型。在将order.id等整数传递给metadata时，请确保将其转换为字符串。
总结
通过本文的指导，您应该能够清晰地理解如何在Stripe Checkout Session中正确集成自定义税率和折扣。关键在于正确地创建Stripe TaxRate、Coupon（或PromotionCode）对象，并以Stripe API要求的格式将它们的ID传递给stripe.checkout.Session.create方法的tax_rates和discounts参数。遵循这些最佳实践，将帮助您构建一个功能完善、错误率低的Stripe支付集成。
