本教程详细指导如何在stripe checkout session中正确集成自定义税率和折扣。我们将探讨stripe tax rate和coupon对象的创建与应用方式，纠正常见的api参数错误，并提供完整的python代码示例，帮助开发者高效、准确地为支付会话添加税费和优惠。
Stripe Checkout Session概述
Stripe Checkout Session是Stripe提供的一种快速、安全地收集付款信息的方式。通过创建Checkout Session，您可以将用户重定向到一个由Stripe托管的支付页面，从而简化了支付流程，并自动处理了许多支付合规性问题。在创建Checkout Session时，我们经常需要集成额外的业务逻辑，例如应用自定义税率和折扣。
1. 理解Stripe中的税率与折扣机制
在Stripe中，税率和折扣分别通过特定的API对象进行管理和应用：
- Stripe TaxRate 对象：表示一个特定的税率，包含税率名称、百分比、是否包含在价格中（inclusive）、以及管辖区域等信息。您可以预先创建这些税率，也可以在需要时动态创建。
-
Stripe Coupon/PromotionCode 对象：
- Coupon (优惠券)：表示一个折扣规则，可以是一个固定金额的折扣 (amount_off) 或一个百分比折扣 (percent_off)。优惠券通常与产品或订单关联，并在Checkout Session中应用。
- PromotionCode (促销码)：是优惠券的一种扩展，允许用户在结账时手动输入代码来应用折扣。
正确地创建和引用这些对象是成功集成税率和折扣的关键。
2. 集成自定义税率
将自定义税率应用于Stripe Checkout Session需要以下步骤：
2.1 创建TaxRate对象
Stripe的TaxRate对象定义了税率的详细信息。您可以选择预先在Stripe管理后台创建税率，或者通过API动态创建。对于动态税率，示例如下：
import stripe
# ... 其他代码 ...
def create_tax_rate(name, percentage, description=None, jurisdiction="US", inclusive=False):
"""
创建或获取一个Stripe TaxRate对象。
为了避免重复创建，实际应用中可以考虑缓存或查询现有税率。
"""
try:
tax_rate = stripe.TaxRate.create(
display_name=name,
description=description if description else name,
percentage=percentage,
jurisdiction=jurisdiction,
inclusive=inclusive,
)
return tax_rate.id
except stripe.error.StripeError as e:
print(f"创建TaxRate失败: {e}")
return None
# 示例：从订单中获取税率信息并创建
# tax_rates_ids = []
# for tax in order.tax.all(): # 假设order.tax是一个包含税率信息的集合
# tax_rate_id = create_tax_rate(tax.name, tax.rate, jurisdiction="RU", inclusive=False)
# if tax_rate_id:
# tax_rates_ids.append(tax_rate_id)2.2 将TaxRate应用于Checkout Session
创建TaxRate对象后，您需要将其ID列表传递给stripe.checkout.Session.create方法的tax_rates参数。
# ... 假设 tax_rates_ids 已经包含了一个或多个 TaxRate ID ...
session = stripe.checkout.Session.create(
payment_method_types=['card'],
line_items=[
{
'price_data': {
'currency': 'usd',
'unit_amount': order.get_total_cost() * 100,
'product_data': {
'name': order.__str__(),
},
},
'quantity': 1,
},
],
# ... 其他参数 ...
tax_rates=tax_rates_ids, # 正确传递税率ID列表
mode='payment',
success_url=DOMAIN + '/success/',
cancel_url=DOMAIN + '/cancel/',
)3. 应用折扣（优惠券）
应用折扣同样需要创建相应的对象，并以正确的格式传递给Checkout Session。
3.1 创建Coupon对象
与TaxRate类似，Coupon也可以预先创建或动态创建。
import stripe
# ... 其他代码 ...
def create_coupon(amount_off=None, percent_off=None, duration='once', currency='usd', name=None):
"""
创建或获取一个Stripe Coupon对象。
"""
if not (amount_off or percent_off):
raise ValueError("必须提供 amount_off 或 percent_off")
coupon_params = {
'duration': duration,
'currency': currency,
'name': name,
}
if amount_off:
coupon_params['amount_off'] = amount_off
elif percent_off:
coupon_params['percent_off'] = percent_off
try:
coupon = stripe.Coupon.create(**coupon_params)
return coupon.id
except stripe.error.StripeError as e:
print(f"创建Coupon失败: {e}")
return None
# 示例：从订单中获取折扣信息并创建
# discount_ids = []
# for discount in order.discount.all(): # 假设order.discount是一个包含折扣信息的集合
# coupon_id = create_coupon(amount_off=discount.amount, duration='once', currency='usd', name=discount.name)
# if coupon_id:
# discount_ids.append(coupon_id)3.2 将Coupon应用于Checkout Session
这是原代码中出现错误的地方。Stripe Checkout Session的discounts参数期望一个包含字典的列表，每个字典应使用'coupon'或'promotion_code'键来引用对应的ID。
错误示例（导致 InvalidRequestError）：
discounts=[{"discounts": '{{COUPON_ID}}'}] # 错误：嵌套了 'discounts' 键这个错误是由于参数结构不正确导致的。Stripe API期望直接使用'coupon'或'promotion_code'作为键。
正确用法：
# ... 假设 coupon_ids 已经包含了一个或多个 Coupon ID ...
# 如果只有一个优惠券ID
discounts=[{'coupon': 'coupon_id_from_stripe'}]
# 如果有多个优惠券ID
discounts_list = [{'coupon': coupon_id} for coupon_id in coupon_ids]
session = stripe.checkout.Session.create(
# ... 其他参数 ...
discounts=discounts_list, # 正确传递折扣信息
mode='payment',
success_url=DOMAIN + '/success/',
cancel_url=DOMAIN + '/cancel/',
)4. 综合示例：同时集成税率与折扣
下面是一个完整的Python Django视图示例，演示了如何在一个Stripe Checkout Session中同时集成动态创建的税率和折扣：
import stripe
from django.views import View
from django.http import JsonResponse
from .models import Order, Tax, Discount # 假设您有这些模型
# 配置Stripe API密钥
# stripe.api_key = 'YOUR_STRIPE_SECRET_KEY' # 或者从settings中加载
class CreateCheckoutSessionOrderView(View):
def get(self, request, *args, **kwargs):
order_id = self.kwargs["order_id"]
DOMAIN: str = 'http://127.0.0.1:8000' # 您的域名
try:
order = Order.objects.get(id=order_id)
except Order.DoesNotExist:
return JsonResponse({'error': 'Order not found'}, status=404)
# 1. 处理税率
tax_rates_ids = []
for tax in order.tax.all(): # 假设Order关联了Tax模型
try:
# 实际应用中，可以先查询Stripe是否存在同名/同百分比的TaxRate，避免重复创建
tax_rate = stripe.TaxRate.create(
display_name=tax.name,
description=tax.name,
percentage=tax.rate,
jurisdiction="RU", # 根据您的业务逻辑设置
inclusive=False, # 税率是否包含在价格中
)
tax_rates_ids.append(tax_rate.id)
except stripe.error.StripeError as e:
print(f"创建Stripe TaxRate失败: {e}")
# 可以在此处添加错误处理逻辑，如记录日志或返回错误响应
# 2. 处理折扣
discounts_list = []
for discount in order.discount.all(): # 假设Order关联了Discount模型
try:
# 实际应用中，可以先查询Stripe是否存在同名Coupon
coupon = stripe.Coupon.create(
amount_off=discount.amount * 100, # amount_off 期望以分(cents)为单位
duration='once', # once, forever, or repeating
currency='usd',
name=discount.name,
)
discounts_list.append({'coupon': coupon.id}) # 正确的折扣参数格式
except stripe.error.StripeError as e:
print(f"创建Stripe Coupon失败: {e}")
# 可以在此处添加错误处理逻辑
# 3. 创建Stripe Checkout Session
try:
session = stripe.checkout.Session.create(
payment_method_types=['card'],
line_items=[
{
'price_data': {
'currency': 'usd',
'unit_amount': order.get_total_cost() * 100, # 确保金额以分(cents)为单位
'product_data': {
'name': order.__str__(),
},
},
'quantity': 1,
},
],
payment_intent_data={
'metadata': {
'order_id': order.id,
},
},
mode='payment',
success_url=DOMAIN + '/success/',
cancel_url=DOMAIN + '/cancel/',
tax_rates=tax_rates_ids, # 传递税率ID列表
discounts=discounts_list, # 传递折扣对象列表
)
return JsonResponse({'id': session.id})
except stripe.error.StripeError as e:
print(f"创建Stripe Checkout Session失败: {e}")
return JsonResponse({'error': str(e)}, status=500)
5. 注意事项与最佳实践
- API参数的准确性：严格遵循Stripe API文档中对每个参数的数据类型和结构要求。discounts参数的结构是导致原代码出错的关键。
-
税率与优惠券的生命周期管理：
- 对于静态不变的税率和优惠券，建议在Stripe管理后台预先创建，或者在应用启动时通过API创建一次并缓存其ID，而不是每次创建Checkout Session时都动态创建，这可以提高性能并避免不必要的API调用。
- 对于动态变化的税率（例如基于用户地理位置或特定促销的优惠券），动态创建是必要的。
- 错误处理：在调用Stripe API时，务必捕获stripe.error.StripeError异常。这能帮助您优雅地处理API调用失败的情况，并向用户提供有意义的反馈。
- 金额单位：Stripe API中所有金额都必须以最小货币单位表示（例如，美元是美分，日元是日元本身）。确保您的代码将order.get_total_cost()和discount.amount等值乘以100以转换为分。
- Stripe Automatic Tax：如果您的业务涉及复杂的税务计算，并且希望Stripe自动处理税务合规性，可以考虑使用Stripe Automatic Tax功能。启用后，Stripe会根据客户的地理位置和产品类型自动计算、收取和报告税费，从而大大简化了税务集成。在这种情况下，您只需在Checkout Session中设置automatic_tax={'enabled': True}，而无需手动传递tax_rates。
结论
通过遵循Stripe API的正确参数结构和最佳实践，您可以高效且准确地在Stripe Checkout Session中集成自定义税率和折扣。理解TaxRate和Coupon对象的创建与应用方式，并特别注意discounts参数的正确格式，将帮助您避免常见的API错误，从而构建健壮的支付解决方案。
