Stripe Checkout 会话中集成自定义税率与折扣-Python教程-PHP中文网

stripe checkout 会话中集成自定义税率与折扣

本文旨在提供一个全面的教程，指导开发者如何在Stripe Checkout会话中正确集成自定义税率和折扣。我们将深入探讨Stripe API中`TaxRate`和`Coupon`对象的创建与应用，纠正常见的参数使用错误，特别是`discounts`参数的错误用法，并提供一个结构化的Python代码示例，帮助您高效、准确地处理支付环节中的税务和优惠逻辑。

概述：Stripe Checkout中的税务与折扣处理

Stripe Checkout是一个预构建的、托管的支付页面，用于简化支付流程。在许多业务场景中，我们需要在Checkout会话中应用自定义的税率和折扣，以满足不同地区税务要求或营销活动需求。Stripe API提供了灵活的机制来管理这些元素，主要通过TaxRate对象和Coupon或PromotionCode对象来实现。

正确地将这些对象集成到stripe.checkout.Session.create调用中是关键。常见的错误包括参数名称或结构不正确，导致API返回InvalidRequestError。本教程将详细介绍如何避免这些问题，并提供一个实用的代码示例。

关键概念

在深入代码之前，理解以下Stripe对象至关重要：

Stripe Checkout Session: Stripe提供的一个托管支付页面实例，通过调用stripe.checkout.Session.create创建。
TaxRate (税率): 代表一个具体的税率，可以包含显示名称、百分比、描述、管辖区等信息。税率可以设置为包含或不包含在价格中（inclusive/exclusive）。
Coupon (优惠券): 代表一个折扣，可以是固定金额折扣（amount_off）或百分比折扣（percent_off）。优惠券通常与一个优惠活动相关联。
PromotionCode (促销码): 允许客户在Checkout页面输入代码来应用折扣。一个促销码可以关联一个或多个优惠券。

集成自定义税率

Stripe允许您在Checkout会话中应用一个或多个税率。这些税率可以是预先在Stripe Dashboard中创建的，也可以通过API动态创建。通常，为了效率和管理，建议预先创建常用税率。

1. 创建或获取TaxRate对象

如果您需要动态创建税率，可以使用stripe.TaxRate.create()。如果税率是固定的，可以直接使用其ID。

import stripe

# 示例：动态创建税率（通常只在税率变动或首次设置时执行）
def create_or_get_tax_rate(display_name, percentage, jurisdiction, inclusive=False):
    # 检查是否已存在同名/同参数的税率，避免重复创建
    # 实际生产中，更好的做法是查询现有税率或从数据库加载预设ID
    try:
        # 尝试检索现有税率，这里简化处理，实际可能需要更复杂的查询逻辑
        # 例如，通过metadata存储自定义ID，或遍历检索
        # 为了演示，我们假设每次都创建，但建议在生产环境中避免
        tax_rate = stripe.TaxRate.create(
            display_name=display_name,
            description=f"{display_name} Tax",
            percentage=percentage,
            jurisdiction=jurisdiction,
            inclusive=inclusive,
        )
        return tax_rate.id
    except stripe.error.StripeError as e:
        print(f"Error creating tax rate: {e}")
        # 如果是已存在错误，可以尝试检索
        # 简化处理，直接返回None或抛出异常
        return None

# 假设您的订单模型中存储了税率信息
# order.tax.all() 返回一个包含税率信息的集合
# For example:
# class Tax(models.Model):
#     name = models.CharField(max_length=100)
#     rate = models.DecimalField(max_digits=5, decimal_places=2) # e.g., 5.00 for 5%
#     jurisdiction = models.CharField(max_length=100, default="US")

登录后复制

2. 将TaxRate应用于Checkout Session

税率可以应用于整个Checkout Session，也可以应用于会话中的单个line_item。当应用于整个会话时，Stripe会将这些税率应用于所有商品行。

在stripe.checkout.Session.create中，通过tax_rates参数传递一个税率ID列表：

Health AI健康云开放平台

专注于健康医疗垂直领域的AI技术开放平台

113

查看详情

# ... (在您的视图或服务函数中)
tax_rate_ids = []
for tax_obj in order.tax.all(): # 假设 order.tax.all() 返回您的自定义税率对象
    # 在生产环境中，您应该从数据库加载预先创建的Stripe TaxRate ID
    # 这里为了演示，我们假设 tax_obj 包含创建Stripe TaxRate所需的信息
    # 并且我们动态创建或获取其ID
    tax_rate_id = create_or_get_tax_rate(
        display_name=tax_obj.name,
        percentage=float(tax_obj.rate), # 确保是浮点数
        jurisdiction=tax_obj.jurisdiction,
        inclusive=False # 根据您的业务逻辑设置
    )
    if tax_rate_id:
        tax_rate_ids.append(tax_rate_id)

# ... 在 stripe.checkout.Session.create 中使用
# session = stripe.checkout.Session.create(
#     # ... 其他参数
#     tax_rates=tax_rate_ids,
#     # ...
# )

登录后复制

集成折扣

折扣可以通过Stripe的Coupon或PromotionCode实现。Coupon定义了折扣的具体内容（如减免金额或百分比），而PromotionCode则允许客户通过输入代码来应用这些优惠券。

1. 创建或获取Coupon对象

与税率类似，优惠券也可以通过API动态创建或预先创建。

# 示例：动态创建优惠券（通常只在优惠活动设置时执行）
def create_or_get_coupon(name, amount_off_cents=None, percent_off=None, currency='usd', duration='once'):
    try:
        if amount_off_cents:
            coupon = stripe.Coupon.create(
                amount_off=amount_off_cents, # 以最小货币单位表示，例如美分
                duration=duration, # once, forever, or repeating
                currency=currency,
                name=name,
            )
        elif percent_off:
            coupon = stripe.Coupon.create(
                percent_off=percent_off,
                duration=duration,
                currency=currency, # 即使是百分比折扣，也需要货币类型
                name=name,
            )
        else:
            raise ValueError("Must provide either amount_off_cents or percent_off")
        return coupon.id
    except stripe.error.StripeError as e:
        print(f"Error creating coupon: {e}")
        return None

# 假设您的订单模型中存储了折扣信息
# order.discount.all() 返回一个包含折扣信息的集合
# For example:
# class Discount(models.Model):
#     name = models.CharField(max_length=100)
#     amount = models.DecimalField(max_digits=10, decimal_places=2, null=True, blank=True) # e.g., 10.00 for $10
#     percentage = models.DecimalField(max_digits=5, decimal_places=2, null=True, blank=True) # e.g., 10.00 for 10%

登录后复制

2. 将折扣应用于Checkout Session

在stripe.checkout.Session.create中，通过discounts参数传递一个包含优惠券ID或促销码ID的列表。请注意，这里的参数结构非常重要，也是原始问题中出错的地方。

正确的discounts参数应该是一个字典列表，每个字典包含一个coupon键或一个promotion_code键。

# ... (在您的视图或服务函数中)
discount_items = []
for discount_obj in order.discount.all(): # 假设 order.discount.all() 返回您的自定义折扣对象
    # 在生产环境中，您应该从数据库加载预先创建的Stripe Coupon ID
    # 这里为了演示，我们假设 discount_obj 包含创建Stripe Coupon所需的信息
    # 并且我们动态创建或获取其ID
    coupon_id = None
    if discount_obj.amount:
        coupon_id = create_or_get_coupon(
            name=discount_obj.name,
            amount_off_cents=int(float(discount_obj.amount) * 100), # 转换为美分
            currency='usd' # 根据您的货币设置
        )
    elif discount_obj.percentage:
        coupon_id = create_or_get_coupon(
            name=discount_obj.name,
            percent_off=float(discount_obj.percentage),
            currency='usd' # 即使是百分比折扣，也需要货币类型
        )

    if coupon_id:
        discount_items.append({"coupon": coupon_id}) # 正确的参数结构！

# ... 在 stripe.checkout.Session.create 中使用
# session = stripe.checkout.Session.create(
#     # ... 其他参数
#     discounts=discount_items,
#     # ...
# )

登录后复制

原始错误分析： 原始代码中使用了discounts=[{"discounts": '{{COUPON_ID}}'}]。Stripe API期望的是discounts列表中的每个元素是一个字典，该字典直接包含"coupon"或"promotion_code"键，而不是再次嵌套一个"discounts"键。因此，Received unknown parameter: discounts[0][discounts]这个错误提示非常准确。

完整代码示例

以下是一个结合了税率和折扣的Django视图示例，基于您提供的原始代码进行修正和优化。

import stripe
from django.conf import settings
from django.http import JsonResponse
from django.views import View
# from .models import Order, Tax, Discount # 假设您有这些模型

# 配置Stripe API密钥
stripe.api_key = settings.STRIPE_SECRET_KEY # 确保在settings.py中配置

# 辅助函数：创建或获取Stripe TaxRate
def create_or_get_stripe_tax_rate(display_name, percentage, jurisdiction, inclusive=False):
    """
    创建一个Stripe TaxRate或返回现有TaxRate的ID。
    在生产环境中，建议预先创建TaxRate并存储其ID，而不是每次都动态创建。
    """
    # 实际应用中，您可能会查询数据库中存储的Stripe TaxRate ID
    # 这里为演示目的，简化为直接创建
    try:
        tax_rate = stripe.TaxRate.create(
            display_name=display_name,
            description=f"{display_name} Tax",
            percentage=percentage,
            jurisdiction=jurisdiction,
            inclusive=inclusive,
        )
        return tax_rate.id
    except stripe.error.StripeError as e:
        # 更健壮的错误处理，例如记录日志
        print(f"Error creating Stripe TaxRate: {e}")
        return None

# 辅助函数：创建或获取Stripe Coupon
def create_or_get_stripe_coupon(name, amount_off_cents=None, percent_off=None, currency='usd', duration='once'):
    """
    创建一个Stripe Coupon或返回现有Coupon的ID。
    在生产环境中，建议预先创建Coupon并存储其ID，而不是每次都动态创建。
    """
    try:
        if amount_off_cents is not None:
            coupon = stripe.Coupon.create(
                amount_off=amount_off_cents,
                duration=duration,
                currency=currency,
                name=name,
            )
        elif percent_off is not None:
            coupon = stripe.Coupon.create(
                percent_off=percent_off,
                duration=duration,
                currency=currency,
                name=name,
            )
        else:
            raise ValueError("Must provide either amount_off_cents or percent_off")
        return coupon.id
    except stripe.error.StripeError as e:
        print(f"Error creating Stripe Coupon: {e}")
        return None

class CreateCheckoutSessionOrderView(View):
    def get(self, request, *args, **kwargs):
        order_id = self.kwargs["order_id"]
        DOMAIN: str = 'http://127.0.0.1:8000' # 生产环境应使用您的实际域名

        # 假设 Order, Tax, Discount 模型已定义并可访问
        # from your_app.models import Order, Tax, Discount
        try:
            # 替换为您的实际订单获取逻辑
            # order = Order.objects.get(id=order_id)
            # 模拟订单数据
            class MockTax:
                def __init__(self, name, rate, jurisdiction):
                    self.name = name
                    self.rate = rate
                    self.jurisdiction = jurisdiction
            class MockDiscount:
                def __init__(self, name, amount=None, percentage=None):
                    self.name = name
                    self.amount = amount
                    self.percentage = percentage
            class MockOrder:
                def __init__(self, id, total_cost, name, taxes, discounts):
                    self.id = id
                    self._total_cost = total_cost
                    self._name = name
                    self._taxes = taxes
                    self._discounts = discounts
                def get_total_cost(self):
                    return self._total_cost
                def __str__(self):
                    return self._name
                def tax(self):
                    # 模拟ManyToManyField
                    class TaxManager:
                        def all(self):
                            return self._taxes
                    return TaxManager()
                def discount(self):
                    # 模拟ManyToManyField
                    class DiscountManager:
                        def all(self):
                            return self._discounts
                    return DiscountManager()

            # 模拟订单数据
            order = MockOrder(
                id=order_id,
                total_cost=100.00, # 示例总价
                name=f"Order #{order_id}",
                taxes=[
                    MockTax(name="Sales Tax", rate=7.5, jurisdiction="US"),
                    # MockTax(name="VAT", rate=20.0, jurisdiction="GB"),
                ],
                discounts=[
                    MockDiscount(name="Welcome Discount", amount=10.00), # 10美元折扣
                    # MockDiscount(name="Promo 5%", percentage=5.0), # 5%折扣
                ]
            )


        except Exception as e:
            return JsonResponse({'error': str(e)}, status=404)

        # --- 处理税率 ---
        tax_rate_ids = []
        for tax_obj in order.tax().all():
            tax_rate_id = create_or_get_stripe_tax_rate(
                display_name=tax_obj.name,
                percentage=float(tax_obj.rate),
                jurisdiction=tax_obj.jurisdiction,
                inclusive=False, # 根据您的业务逻辑调整
            )
            if tax_rate_id:
                tax_rate_ids.append(tax_rate_id)

        # --- 处理折扣 ---
        discount_items = []
        for discount_obj in order.discount().all():
            coupon_id = None
            if discount_obj.amount is not None:
                coupon_id = create_or_get_stripe_coupon(
                    name=discount_obj.name,
                    amount_off_cents=int(float(discount_obj.amount) * 100),
                    currency='usd',
                )
            elif discount_obj.percentage is not None:
                coupon_id = create_or_get_stripe_coupon(
                    name=discount_obj.name,
                    percent_off=float(discount_obj.percentage),
                    currency='usd', # 即使是百分比折扣，也需要货币类型
                )

            if coupon_id:
                discount_items.append({"coupon": coupon_id}) # 正确的参数结构

        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__(),
                                'description': f"Purchase for order {order.id}",
                            },
                        },
                        'quantity': 1,
                        # 如果需要对特定商品行应用税率，可以在这里添加 'tax_rates': [...]
                        # 但通常在会话级别应用更常见
                    },
                ],
                payment_intent_data={
                    'metadata': {
                        'order_id': order.id,
                    },
                },
                mode='payment',
                success_url=DOMAIN + '/success/',
                cancel_url=DOMAIN + '/cancel/',
                tax_rates=tax_rate_ids,      # 应用税率
                discounts=discount_items,    # 应用折扣
            )
            return JsonResponse({'id': session.id})
        except stripe.error.StripeError as e:
            # 捕获Stripe API错误
            return JsonResponse({'error': str(e)}, status=500)
        except Exception as e:
            # 捕获其他未知错误
            return JsonResponse({'error': f"An unexpected error occurred: {e}"}, status=500)

登录后复制

注意事项与最佳实践

Stripe API Key: 确保您的Stripe secret key已正确配置在Django settings.py 中，并被stripe.api_key引用。
TaxRate 和 Coupon 的生命周期: 在生产环境中，TaxRate和Coupon对象通常是一次性创建的（例如，在Stripe Dashboard中，或通过管理界面/脚本）。然后，您只需在数据库中存储它们的Stripe ID，并在创建Checkout Session时引用这些ID。动态创建（如示例中所示）虽然可行，但在每次用户结账时都调用Stripe API创建新对象会增加延迟和不必要的API请求。
错误处理: 务必在API调用周围添加try-except块来捕获stripe.error.StripeError，以便优雅地处理网络问题、无效参数或其他Stripe API返回的错误。
货币单位: Stripe API处理金额时通常使用最小货币单位（例如，美元使用美分）。确保在传递unit_amount和amount_off时进行正确的转换（乘以100）。
**税率的包含性 (

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

大家都在看：

Python使用Pandas进行复杂表结构处理的解决方案【教学】 Python使用强化学习解决决策问题的建模训练思路解析【教学】 python是什么语言写的 Python深度学习训练跨模态检索模型的特征融合策略解析【教程】 Python模块中访问和管理其内部全局变量的最佳实践