Stripe Checkout Session中集成自定义税率与折扣的指南

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Stripe Checkout Session中集成自定义税率与折扣的指南

2025-12-07

浏览次数：次

返回列表

Stripe Checkout Session中集成自定义税率与折扣的指南

本文旨在指导开发者如何在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的一个实例，可以用于分发和限制使用。

Openflow

一键极速绘图，赋能行业工作流

查看详情

通过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支付集成。

以上就是Stripe Checkout Session中集成自定义税率与折扣的指南的详细内容，更多请关注其它相关文章！

# 实际应用 # 昌乐优化网站设计公司 # 网站首页怎么优化推广 # 青海建设厅网站 # 怎样制作网络推广网站 # 餐饮店营销推广文案 # 赫莲娜推广营销规划 # 怎么建立网上网站推广 # 永康网站建设规划的内容 # 如何在微信上推广seo # 7月地产营销推广主题 # 正确地 # 如何处理 # 用户登录 # 转换为 # 将其 # js # 子类 # 应用于 # 自定义 # 您的 # red # 币 # cos # api调用 # 地理位置 # django # ai # session # app # go # json