Stripe Checkout Session中集成自定义税率与折扣的教程

本教程详细指导如何在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错误，从而构建健壮的支付解决方案。

# python # js # json # go # app # session # ai # django # 地理位置 # api调用 # cos # 币

返回目录在线咨询

上一篇：虚拟主机无限建站：如何备份和恢复数据以防止数据丢失？
下一篇：Java正则表达式_动力节点Java学院整理

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

全网整合营销服务商