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

php中文网
发布: 2025-12-07 17:53:02
原创
989人浏览过

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的一个实例,可以用于分发和限制使用。

Manus
Manus

全球首款通用型AI Agent,可以将你的想法转化为行动。

Manus 250
查看详情 Manus

通过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)
登录后复制

注意事项

  1. Stripe API密钥管理: 确保您的Stripe API密钥(stripe.api_key)已正确配置,并且在生产环境中使用秘密密钥。
  2. 金额单位: Stripe API要求所有金额(unit_amount, amount_off等)都以最小货币单位表示(例如,美元使用美分,欧元使用欧分)。因此,在传递金额时,请务必将其乘以100并转换为整数。
  3. 税率和优惠券的生命周期: 在生产环境中,频繁地创建新的TaxRate和Coupon对象可能不是最佳实践。通常,您会预先在Stripe Dashboard或通过API创建这些对象,然后在代码中通过其ID引用它们。只有当税率或折扣规则频繁变化且无法预设时,才考虑动态创建。
  4. 错误处理: 在与Stripe API交互时,务必添加健壮的错误处理机制,捕获stripe.error.StripeError及其子类,以便优雅地处理API调用失败的情况。
  5. 自动税收 (Automatic Tax): Stripe还提供了自动税收功能 (automatic_tax={'enabled': True}),可以根据客户的地理位置和产品类型自动计算税费。如果您的业务场景需要复杂的全球税收合规,可以考虑使用此功能,它会替代手动传递tax_rates。
  6. 测试: 在Stripe的测试模式下充分测试您的集成,确保税率和折扣的计算和应用符合预期。
  7. 数据类型: 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中集成自定义税率与折扣的指南的详细内容,更多请关注php中文网其它相关文章!

最佳 Windows 性能的顶级免费优化软件
最佳 Windows 性能的顶级免费优化软件

每个人都需要一台速度更快、更稳定的 PC。随着时间的推移,垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是,许多工具可以让 Windows 保持平稳运行。

下载
来源:php中文网
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn
最新问题
开源免费商场系统广告
热门教程
更多>
最新下载
更多>
网站特效
网站源码
网站素材
前端模板
关于我们 免责申明 举报中心 意见反馈 讲师合作 广告合作 最新更新 English
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号 技术交流群
PHP中文网订阅号
每天精选资源文章推送
PHP中文网APP
随时随地碎片化学习

Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号