支付分账
概述
支付分账允许您将收到的 PIX（Cash-In）金额自动分配给多个收款方。当付款确认后，系统会计算每个收款方的份额并自动执行转账（PIX-OUT）。
分账在创建收款时（Cash-In 或静态二维码）配置。无法为已创建的交易添加分账。
使用场景
电商平台
在卖家和平台（佣金）之间自动分配付款。
合作伙伴
按预定义百分比在合作伙伴之间分配收入。
加盟店
自动将特许权使用费和费用转给总部。
服务提供商
自动转账给服务提供商，平台保留服务费。
工作原理
生成 PIX Cash-In 时，包含 splits 数组，指定收款方及其金额（固定或百分比）。
当付款方完成 PIX 付款后，CashIn webhook 以 CONFIRMED 状态发送。
系统计算每个收款方的金额（扣除手续费后）并创建分账项。
根据配置的频率，金额自动通过 PIX 发送给每个收款方。
每笔转账都会发送一个包含结果（成功或失败）的 CashOut webhook。
分账类型
FIXED -- 固定金额
收款方收到固定金额，与总付款金额无关。
{
"type": "FIXED",
"value": 10.00
}金额单位为 BRL，最多 2 位小数：10.00 = R$ 10.00。
PERCENTAGE -- 百分比
收款方收到付款总额（手续费前）的百分比。
{
"type": "PERCENTAGE",
"value": 10
}百分比直接提供：10 = 10%，25.5 = 25.5%。
金额格式
分账金额使用与 transaction.value 字段相同的格式 -- 以 BRL 为单位，最多 2 位小数。
固定金额 (FIXED)
| BRL 金额 | value 字段 |
|---|---|
| R$ 0.01 | 0.01 |
| R$ 1.00 | 1.00 |
| R$ 10.00 | 10.00 |
| R$ 100.00 | 100.00 |
| R$ 1,500.50 | 1500.50 |
最小值： 0.01
百分比 (PERCENTAGE)
| 百分比 | value 字段 |
|---|---|
| 1% | 1 |
| 5% | 5 |
| 10% | 10 |
| 25.5% | 25.5 |
| 33.33% | 33.33 |
| 50% | 50 |
值直接表示百分比。 无需额外乘以倍数。
执行频率
频率决定累积的分账何时执行。它按账户配置，而非按交易配置。
| 频率 | 行为 |
|---|---|
IMMEDIATE | PIX-IN 确认后立即执行 |
HOURLY | 累积并每小时执行一次 |
DAILY | 累积并每天执行一次 |
WEEKLY | 累积并每周执行一次 |
当频率为 DAILY 或 WEEKLY 时，同一收款方多笔交易的分账会合并为一笔 PIX-OUT。这可以降低交易成本。
分账中的 immediate 字段
单个分账中的 immediate 字段允许您覆盖该特定分账的账户频率：
{
"pixKey": "urgent@email.com",
"pixKeyType": "EMAIL",
"name": "Urgent Supplier",
"document": "12345678000199",
"type": "FIXED",
"value": 50.00,
"immediate": true
}当 immediate: true 时，即使账户配置为 DAILY 频率，分账也会在 PIX-IN 确认后立即执行。
完整示例
场景：3 个收款方的电商平台
电商平台从客户收到 R$ 100.00。金额应如下分配：
- 卖家：70% 的金额
- 平台：20% 的金额
- 配送员：固定 R$ 10.00
{
"transaction": {
"value": 100.00,
"description": "Order #12345 - Marketplace",
"externalId": "ORDER-12345",
"generateQrCode": true
},
"payer": {
"fullName": "Carlos Oliveira",
"document": "12345678901"
},
"splits": [
{
"pixKey": "seller@email.com",
"pixKeyType": "EMAIL",
"name": "John's Store",
"document": "98765432000188",
"type": "PERCENTAGE",
"value": 70,
"immediate": false
},
{
"pixKey": "platform@marketplace.com",
"pixKeyType": "EMAIL",
"name": "Marketplace Ltd",
"document": "11222333000144",
"type": "PERCENTAGE",
"value": 20,
"immediate": false
},
{
"pixKey": "12345678901",
"pixKeyType": "CPF",
"name": "Delivery Person Silva",
"document": "12345678901",
"type": "FIXED",
"value": 10.00,
"immediate": true
}
]
}付款后的结果（收到 R$ 100.00）：
| 收款方 | 类型 | 计算 | 金额 |
|---|---|---|---|
| 卖家 | 70% | R$ 100.00 x 70% | R$ 70.00 |
| 平台 | 20% | R$ 100.00 x 20% | R$ 20.00 |
| 配送员 | 固定 | R$ 10.00 | R$ 10.00 |
| 合计 | R$ 100.00 |
当存在平台手续费（fee）时，百分比计算基于总额（手续费前）。手续费从分账后的剩余金额中扣除。
限制和约束
| 约束 | 值 |
|---|---|
| 每笔交易最大收款方数 | 10 |
| 每笔分账最小金额 (FIXED) | 0.01（R$ 0.01） |
| 每笔分账最小百分比 | 0.01（0.01%） |
| 最大小数位数 | 2 |
| 分账总和 | 不能超过交易金额 |
如果固定分账 + 总额百分比 + 手续费的总和超过交易金额，API 将返回 400 Bad Request 错误。
无金额的静态二维码
对于未定义金额的静态二维码（由付款方提供金额），仅允许 PERCENTAGE 分账。FIXED 分账将被拒绝，因为创建时最终金额未知。
Webhooks
PIX-IN 已确认（含分账）
当付款确认后，发送标准 CashIn webhook。分账在后台自动处理。
{
"event": "CashIn",
"status": "CONFIRMED",
"transactionId": "12345",
"externalId": "ORDER-12345",
"originalAmount": 100.00,
"finalAmount": 99.50,
"feeAmount": 0.50
}分账 PIX-OUT（执行）
对于每个分账收款方，执行一笔 PIX-OUT 并发送 CashOut webhook：
{
"event": "CashOut",
"status": "CONFIRMED",
"transactionId": "67890",
"externalId": "SPLIT-12345-seller",
"originalAmount": 70.00,
"finalAmount": 70.00,
"counterpart": {
"name": "John's Store",
"document": "*.765.432/0001-**"
}
}分账的 CashOut webhooks 与常规 Cash-Out webhooks 遵循相同的格式和配置。在控制面板的 Settings -> Webhooks 中配置您的 webhooks。