Flask集成Stripe Checkout向多个Connect账户分账失败排查

问题原因 #

1. transfer_group参数使用错误：该字段是用于标记一组转账的字符串标识符，你传入了数组格式的transfer_data，导致Stripe无法解析，直接抛出格式错误。
2. Checkout Session不支持直接指定多转账目标：单个Checkout Session对应的Payment Intent无法在创建时直接设置多个Connect账户转账，必须在付款完成后通过Transfers API单独创建每笔转账。

解决步骤 #

1. 修正Checkout Session创建代码 #

生成一个唯一的字符串作为transfer_group，用于后续关联所有拆分转账，移除错误的数组赋值：

import uuid
import stripe

def redirect_stripe_teams(price, recipient_ids, total_amount):
    # 生成唯一的转账组标识，建议关联业务订单ID
    transfer_group = f"order_{uuid.uuid4().hex}"
    
    session = stripe.checkout.Session.create(
        mode="payment",
        line_items=[{"price": price.id, "quantity": 1}],
        payment_intent_data={
            "application_fee_amount": 123,
            "transfer_group": transfer_group,  # 此处为字符串，而非数组
        },
        success_url="http://127.0.0.1:5000/success?session_id={CHECKOUT_SESSION_ID}",
        cancel_url="http://127.0.0.1:5000/cancel",
    )
    
    # 关键：将transfer_group、recipient_ids、total_amount存入数据库，供后续webhook使用
    # 示例：db.session.add(Order(session_id=session.id, transfer_group=transfer_group, recipients=recipient_ids, total=total_amount))
    # db.session.commit()
    
    return session

2. 配置Stripe Webhook处理付款完成事件 #

当Checkout Session付款成功后，通过checkout.session.completed事件触发，循环创建每笔转账到对应Connect账户：

from flask import request, jsonify

@app.route('/stripe-webhook', methods=['POST'])
def stripe_webhook():
    payload = request.get_data(as_text=True)
    sig_header = request.headers.get('Stripe-Signature')
    # 从Stripe控制台获取你的Webhook签名密钥
    endpoint_secret = "whsec_xxxxxxxxxxxxxx"

    try:
        event = stripe.Webhook.construct_event(payload, sig_header, endpoint_secret)
    except (ValueError, stripe.error.SignatureVerificationError):
        return jsonify({"error": "Invalid webhook event"}), 400

    if event['type'] == 'checkout.session.completed':
        session = event['data']['object']
        # 从数据库取出之前存储的转账信息
        # 示例：order = Order.query.filter_by(session_id=session.id).first()
        # recipient_ids = order.recipients
        # total_amount = order.total
        # transfer_group = order.transfer_group

        num_recipients = len(recipient_ids)
        # 转换为最小货币单位（如美元用分，人民币用分），避免浮点数精度问题
        amount_per_recipient = int(total_amount / num_recipients)

        # 循环创建每个Connect账户的转账
        for account_id in recipient_ids:
            stripe.Transfer.create(
                amount=amount_per_recipient,
                currency="usd",  # 需与付款货币一致
                destination=account_id,
                transfer_group=transfer_group,
            )

    return jsonify({"status": "success"}), 200

关键注意事项 #

• 货币单位处理：Stripe API要求金额为最小货币单位（如1美元需传100），必须将计算结果转为整数，禁止使用浮点数。
• Webhook配置：需在Stripe控制台配置Webhook端点，选择checkout.session.completed事件，本地测试可使用ngrok生成HTTPS地址。
• 金额校验：确保总金额 = 应用手续费（application_fee_amount） + 所有转账金额之和，避免资金异常。
• Connect账户有效性：确认recipient_ids均为已关联的有效Stripe Connect账户ID。

内容的提问来源于stack exchange，提问作者Oliver Edwards