通道矩阵
Hosted payin 在需要时接受
payer_name、payer_document 和
payer_phone。Payout 的 flow_type 是 B2C、B2B 或 P2P，由服务端
控制的通道配置决定。
Hosted payin 与 wallet
PY 的bank_transfer 和 wallet、CO 的 bank_transfer、EC 的 wallet
会返回 payment_url。创建时使用 idempotency_key，等待签名的
payin_received webhook，然后用 GET /v1/payins/{payinID} 查询。
wallet 是 collect push，不返回 URL。付款人在钱包应用中批准，
结果通过 webhook 返回，通常约 15 分钟。CO/COP/bank_transfer 使用
hosted PSE checkout。COP 金额必须为整数。
巴西
巴西提供两个 payout 方法和一个 hosted PIX payin。请以GET /v1/payouts/methods 与 GET /v1/payins/methods 的实时结果为准。
PIX 与 TED payout
PIX 使用method: "pix" 和 PIX key：CPF、CNPJ、邮箱、巴西手机号
（+55 加 10 位固话或 11 位手机号）或随机 EVP/UUID key。CPF 与 CNPJ 会校验巴西
校验位；此方法不需要银行或账户字段。
TED 使用 method: "bank_transfer"，并提供银行、分行、账户类型、账户
号码、姓名和 CPF/CNPJ。银行代码必须来自 GET /v1/payouts/banks；
分行和账户类型必填。CPF/CNPJ 会在发送前校验；部分目的银行只接受
非 CPF 文档，请遵循目录和返回的校验错误。
两种 BRL 方法最多接受两位小数。遇到不明确的 timeout 时，使用相同的
幂等 key 查询原 payout，不要创建替代操作。
Hosted PIX payin
创建BR/BRL/pix 时金额至少为 1 BRL，并发送 payer_name 与
payer_document。响应包含 payment_url，初始状态为 pending；将
付款人重定向到该 URL。
"1"。重试时使用相同 key 以获取
原来的 hosted charge。
Payout 与安全
在表单中展示选项前先调用GET /v1/payouts/methods 和
GET /v1/payouts/banks。遇到 timeout 或 5xx 时保留同一个 key 并查询
原资源；CBPay 不会自动重发不明确的资金操作。
入站 callback 会被认证，出站 webhook 带有 X-Webhook-Signature。重复
投递必须以幂等方式处理。
生命周期与 webhook
Payin 的最终状态是completed 和 failed；pending 和 processing
是过渡状态。
常见错误
FAQ
可以选择供应商或 PY fallback 吗？
可以选择供应商或 PY fallback 吗？
不可以。集成方只能选择中性通道；variant 由服务端控制并签名。
timeout 后应该怎么做？
timeout 后应该怎么做？
保留相同的 idempotency key 并查询原资源，不要创建第二笔资金操作。
payin 可以查询多久？
payin 可以查询多久？
上游查询只支持创建后 12 个月内；请保留 CBPay charge 和 webhook 记录。