实现异步支付方式（Boleto、Pix…

在支付连接器中实现 Boleto、Pix、银行转账或浏览器跳转类异步支付时，正确返回 undefined 状态、使用 callbackUrl 通知/重试、校验 X-VTEX-signature，并为每种异步方式配置合理的 delayToCancel。

适用场景

解决思路

1. 判断支付方式是否异步：若收单方无法同步返回最终状态，则视为异步支付，Create Payment 响应必须返回 status: "undefined"；常见异步方式包括 Boleto Bancário（BankInvoice）、Pix、银行转账和跳转式认证；同步方式（信用卡、即时授权的借记卡）可返回最终状态。
2. 异步支付绝不能提前返回 "approved" 或 "denied"：只有收单方实际确认或拒绝后才能返回最终状态，否则会导致未收款就发货或误取消可完成的支付。
3. 非 VTEX IO 环境下，callbackUrl 是通知端点：向它 POST 更新后的状态，并带上 X-VTEX-API-AppKey 和 X-VTEX-API-AppToken 请求头。
4. VTEX IO 环境下，callbackUrl 是重试端点：向它 POST（无 payload）以触发 Gateway 重新调用 POST /payments；callbackUrl 格式通常为 https://{account}.vtexpayments.com.br/payment-provider/transactions/{txId}/payments/{paymentId}/retry，POST body 为 { paymentId } 即可让 Gateway 重新调用你的 authorize()。
5. 始终保留 callbackUrl 中的 X-VTEX-signature 查询参数，绝不剥离或修改它。
6. 必须使用请求中提供的原始 callbackUrl，包括所有查询参数，不得硬编码或手动构造；callbackUrl 含交易级认证令牌，硬编码或修改会被 Gateway 拒绝，导致支付永远停留在 undefined。
7. inboundRequestsUrl 仅支持服务器到服务器的 POST，不支持浏览器 GET 跳转；若支付流程需要用户浏览器跳回（如 PayPal、3DS），必须创建自定义公开路由。
8. 为跳转式流程创建自定义公开路由：在 service.json 中声明路由（如 "providerCallback": { "path": "/_v/my-connector/callback", "public": true }），并在 node/index.ts 中通过 PaymentProviderService 的 routes 注册 handler。
9. 实现跳转回调 handler：接收浏览器 GET，从 VBase 读取支付记录，根据用户操作更新状态（如 user-returned 或 user-cancelled），POST 到存储的 callbackUrl 触发 Gateway 重试，最后将用户重定向回 VTEX checkout。
10. 在 authorize() 中为外部支付提供商使用自定义路由作为 return_url 和 cancel_url（而非 inboundRequestsUrl），并存储 callbackUrl、returnUrl 和外部订单 ID，返回 status: 'undefined' 与 paymentUrl。
11. 为异步方式正确计算 delayToCancel：Pix 必须在 900 到 3600 秒（15–60 分钟）之间，与二维码有效期一致；BankInvoice（Boleto）根据配置的到期日/付款截止时间计算（例如距到期日的秒数）；其他异步方式遵循提供商文档的过期 SLA；绝不能超过底层支付的实际有效期。
12. 不要对所有异步方式硬编码 delayToCancel = 604800（7 天）：7 天只是 Gateway 对 undefined 状态重试的内部安全上限，不代表每种异步方式都应使用该值。
13. Create Payment 必须幂等且能应对重复调用：先按 paymentId 查找已有记录，若存在则不再调用收单方，直接返回基于本地持久化状态的响应，状态可随回调从 "undefined" 演变为 "approved" 或 "denied"。
14. 首次调用时才调用收单方一次，保存响应、callbackUrl 和收单方引用；异步方式初始状态为 "undefined"，同步方式使用收单方返回的状态。
15. 收单方 webhook 到达时，先更新本地状态，再使用存储的原始 callbackUrl 通知 Gateway（非 VTEX IO 带 X-VTEX-API-AppKey/AppToken 头）。
16. 为 callbackUrl 通知实现指数退避重试（如最多 3 次，基础延迟 1 秒，延迟按 2 的幂增长）；全部失败后仍可依赖 Gateway 通过 /payments 的重试作为安全网。
17. 跳转式流程的状态演变：pending →（用户在外部站点完成）→ user-returned →（authorize 被重新调用）→ approved；pending →（用户取消）→ user-cancelled →（authorize 被重新调用）→ denied。
18. 用集合分类异步支付方式，例如 ASYNC_PAYMENT_METHODS = new Set(["BankInvoice", "Pix"])，并提供 isAsyncPaymentMethod 辅助函数。
19. 确保自定义路由在 service.json 中声明，并通过 PaymentProviderService 的 routes 传入，否则 VTEX IO 不会暴露该路由。
20. 构建回调 URL 时使用正确的 IOContext 访问方式：this.context.vtex.account 和 this.context.vtex.workspace，而非 this.context.account；非 master workspace 需加 workspace 前缀。

适用边界 · 注意事项

• 不要用于 PPP 端点契约与响应结构问题——应使用 payment-provider-protocol 技能。
• 不要用于 paymentId/requestId 幂等与状态机逻辑——应使用 payment-idempotency 技能。
• 不要用于 PCI 合规与 Secure Proxy 卡处理——应使用 payment-pci-security 技能。