Payout
Quick Reference
What由钱包提供资金的出账付款（payout）
Why通过单一统一端点向拉美各地的供应商、合作伙伴和客户付款
Reading Time8 分钟
DifficultyIntermediate
Prerequisites身份验证 → 一个有余额的钱包
什么是 payout
Payout 是出账流程——资金离开平台，与收款相反。与从付款人收款不同，您从钱包向受益人发送资金。单一端点处理所有支付通道；type_payout 字段选择使用哪个通道。
| 特性 | 详情 |
|---|---|
| 方向 | 出账（付款） |
| 资金来源 | 从钱包扣款（wallet_uuid） |
| 通道 | PIX、TED、SPEI、LATAM 银行转账、现金提取 |
| 市场 | 巴西、墨西哥及拉美（阿根廷、智利、哥伦比亚、秘鲁、厄瓜多尔、危地马拉、洪都拉斯） |
| 幂等性 | 通过 transaction_reference 按钱包 |
| 确认 | 通过 Webhook 异步确认 |
Payout 通道
type_payout | 目标对象 | 典型市场 |
|---|---|---|
pix | pix_destination | 巴西 |
ted | bank_destination | 巴西 |
spei | bank_destination | 墨西哥 |
bank_transfer | bank_destination | LATAM |
cash_pickup | cash_destination | 厄瓜多尔及现金网络 |
工作原理
1
Merchant 创建 payout
您的服务端调用 POST /api/v1/bank/wallet/payout/，传入 wallet_uuid、type_payout、value、description 和对应的目标对象。
2
A55 校验并路由
A55 校验载荷、检查钱包余额，并路由到符合条件的 provider。
3
Provider 发送资金
provider 将资金转入受益人账户（现金 payout 则生成提取码）。
4
Webhook 确认结果
当 payout 到达终态（realized、returned、error 等）时，A55 向您的 webhook_url 发送 Webhook。
Payout 流程
Payout 生命周期
| 状态 | 说明 |
|---|---|
| pending | 已创建，等待处理 |
| issued | 已发送至 provider |
| realized | 已确认并结算 |
| returned | 被接收银行退回 |
| canceled | 已取消 |
| error | 处理失败 |
| expired | 已过期 |
将 Webhook 视为事实来源
同步响应返回初始状态。payout 通常会从 issued 异步推进到 realized。设置 webhook_url 并依赖 Webhook 获取最终结果。
幂等性
Payout 通过 transaction_reference 按钱包实现幂等。如果省略，A55 会生成一个。对同一钱包重用相同引用会被拒绝并返回 errors.wallet.payout_already_exists，从而在重试时保护您免于发送重复 payout。
Provider 路由与故障转移
A55 根据内部规则（能力、余额和账户配置）为所选通道和货币选择符合条件的 provider。如果第一个 provider 失败，编排器会在将 payout 标记为 error 之前自动尝试下一个符合条件的 provider。
API 参考
完整的请求和响应 schema、错误码以及各通道示例位于 API 参考：
| 操作 | 端点 |
|---|---|
| 创建 payout | POST /api/v1/bank/wallet/payout/ |
| Payout 列表 | GET /api/v1/bank/wallet/payout/ |
| 查询 payout | GET /api/v1/bank/wallet/payout/{payout_uuid}/{wallet_uuid}/ |
| Payout Webhook | 向您的 webhook_url 发送通知 |