多租户Next.js/Prisma集成SumUp Reader Checkout的Webhook租户识别困境

针对你遇到的多租户Webhook循环问题，结合SumUp Reader Checkout API的实际设计，逐个解答你的问题：

1. SumUp推荐的多租户元数据传递方式 #

SumUp官方推荐使用Checkout创建接口的顶层metadata字段传递自定义业务数据，这是专门为这类场景设计的：

• 创建Checkout时，直接在请求体中添加metadata: { companyId: "你的租户ID" }，无需嵌套在affiliate.tags.metadata里。
• 该字段支持任意键值对，SumUp会在所有相关Webhook事件中完整返回这个metadata，不需要额外调用认证接口获取。
• 若你需要使用affiliate相关标识，也可以直接将companyId作为affiliate.tags的数组项传入（如tags: ["companyId:123"]），Webhook事件会直接带回affiliate.tags数组，解析即可拿到租户ID。

2. 初始Webhook能否返回部分关联元数据？ #

可以。SumUp的Webhook事件（如checkout_completed、checkout_canceled）默认会返回Checkout对象的核心字段，包括：

• 顶层metadata（如果你创建时已设置）
• checkout_reference（自定义业务关联ID）
• affiliate下的tags和基础信息
  这些数据都直接包含在Webhook的POST payload中，无需调用GET /checkouts/{id}接口。你之前的循环问题，本质是把租户元数据存到了需要认证才能访问的嵌套层级里，换用顶层字段即可解决。

注意：接收Webhook时必须验证签名（用SumUp提供的Webhook密钥），防止伪造请求，但验证签名不需要租户的accessToken。

3. return_url传参、自定义checkout_reference等替代方案 #

除了metadata，还有两种可靠的替代方案：

• 自定义checkout_reference：创建Checkout时设置checkout_reference: "company_123_order_789"，可以将租户ID和业务ID拼接（用固定分隔符区分），Webhook事件会直接返回这个字段，解析后即可拿到companyId，进而查询数据库获取租户凭证。
• return_url传参：创建Checkout时设置return_url: "https://你的域名.com/payment-return?companyId=123&checkoutId={checkoutId}"，SumUp会在支付完成后自动替换{checkoutId}为实际ID并跳转。但这是前端跳转逻辑，只能作为Webhook的补充（Webhook是后台异步通知，可靠性更高），不能替代Webhook处理业务逻辑。

额外实践建议 #

• 立即迁移到顶层metadata或checkout_reference字段，避免依赖需要认证的嵌套数据。
• 在SumUp后台配置Webhook时，开启签名验证，确保请求来自合法的SumUp服务。
• 测试时使用SumUp Sandbox环境，验证Webhook payload是否正确携带你的租户元数据。

内容的提问来源于stack exchange，提问作者Abdulrahman Alkurdi