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

堆友

Alibaba Design打造的设计师全成长周期服务平台，旨在成为设计师的好朋友

759 查看详情

通过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中集成自定义税率与折扣的指南的详细内容，更多请关注其它相关文章！

# 实际应用  # 社交网站推广工作内容  # 网站建设运营策划  # 网站优化推广专家  # 泰州专业站seo优化  # 伴读营如何做营销推广  # 常州营销推广教程  # 唐山seo内部优化  # 网站建设跟推广的区别  # 海外推广网站有哪些  # 许昌网站推广优化哪里不错  # 是否存在  # 正确地  # 转换为  # 中文网  # 将其  # js  # 子类  # 应用于  # 自定义  # 您的  # red  # 币  # cos  # api调用  # 地理位置  # django  # ai  # session  # app  # go  # json 

相关栏目： 【 Google疑问12 】 【 Facebook疑问10 】 【 优化推广96088 】 【 技术知识133117 】 【 IDC资讯59369 】 【 网络运营7196 】 【 IT资讯61894 】

相关推荐： WPS文字如何进行简繁转换  LocoySpider如何批量采集电商商品_LocoySpider电商采集的模板应用  驱动人生：游戏修复指南  《图怪兽》退出登录方法  mysql镜像配置如何设置用户权限组_mysql镜像配置用户组与权限分级管理方法  掌握CSS :has() 选择器：父选择器、嵌套限制与常见陷阱解析  传统曲艺莲花落的表演形式是  Python中深度嵌套字典与列表的数据提取与条件过滤指南  解决Go encoding/json 将JSON大数字解析为浮点数的问题  J*aScript类型数组_TypedArray使用  动漫之家观看全集库 动漫之家免费资源网地址  如何在CSS中设置背景图像：一个全面指南  《荔枝fm》导出文件教程  圆通快递官方入口不需要登录 在线查询入口快速查询  解决Windows上Composer PATH变量冲突导致的命令无法识别问题  风车动漫官网首页入口登录 风车动漫在线观看正版地址  多多买菜门店端app订单查看方法  手机自动关机是怎么回事？如何修复？手机异常关机的原因排查与修复技巧  Win11怎么开启HDR_Windows 11显示器画质增强设置  《火影忍者：木叶高手》快速升级攻略  J*aScript二进制处理_ArrayBuffer与Blob  如何高效地基于键列值映射DataFrame中的多个列  TikTok笔记文字无法编辑如何解决 TikTok笔记文字编辑优化方法  掌握产品代码正则表达式：避免常见陷阱与精确匹配  HTML与J*aScript实现下拉菜单驱动的动态表格：构建交互式维修表单  抖音号怎么解除企业认证改成个人？改成个人有影响吗？  QQ网页版官方账号登录入口 QQ网页版网页版入口快速导航  yy漫画官方网站登录入口_yy漫画在线阅读页面地址  漫蛙漫画直连入口 _ manwa官方备用入口实时检测  申通快递查询 申通物流快递单实时查询入口  J*a实现任务清单管理_集合框架综合入门练手  电脑视频号|直播|如何分享屏幕  键盘声音异常怎么回事_键盘异响怎么处理  CSS绝对定位与溢出控制：实现背景元素局部显示不触发滚动条  批改网官网首页登录 批改网学生用户登录入口  菜鸟裹裹怎样获得取件码_菜鸟裹裹获得取件码步骤  《随手记》备份数据方法  包子漫画官网链接官方地址 包子漫画在线观看官网首页入口  Win10锁屏时间怎么设置 Win10调整自动锁屏时间方法  PHP中动态类名访问的类实例类型提示与静态分析实践  pubmed数据库官方主页_pubmed学术论文查找官网直达  抖音号升级成企业资质怎么弄？有什么好处？  全球各国上班时间表外贸邮件时间  Python csv 模块处理非字符串数据：列表写入 CSV 文件的机制解析  使用VS Code调试Python代码：从入门到精通  mysql离线安装后如何启动_mysql离线安装完成后启动服务的方法  mysql中如何分析索引使用情况_mysql索引使用分析方法  《虎扑》取消评分记录方法  QQ邮箱注册地址 免费获取QQ邮箱账号  在Spring Boot Thymeleaf中利用布尔属性实现容器的条件显示 

 2025-12-07