docs
集成指南

分账付款

概述

分账付款允许将收到的 PIX（Cash-In）金额自动分配给多个收款方。付款确认后，系统会计算每个收款方的份额，并自动执行转出（PIX-OUT）。

分账在创建收款时（Cash-In 或静态二维码）配置。无法为已创建的交易添加分账。

使用前，分账功能必须在您的账户中启用。未启用时，提交带有 splits 的收款会以 400 被拒绝，errorCode 为 SPLIT_NOT_CONFIGURED。启用状态、执行频率、最低累计金额和每笔交易的收款方上限由支持团队按账户设置（suporte@fypay.me [A DEFINIR]）；没有用于修改这些设置的公开端点。

使用场景

电商平台

在卖家和平台（佣金）之间自动分配付款。

合伙企业

按预先设定的百分比在合伙人之间分配收入。

加盟店

自动向加盟总部转付特许权使用费和费用。

服务提供商

自动向服务提供商转付款项，同时保留平台手续费。

工作原理

生成 PIX Cash-In 时，加入 splits 数组，包含收款方及其金额（固定或百分比）。

付款人完成 PIX 后，会发送状态为 CONFIRMED 的 CashIn webhook。

系统计算每个收款方的金额（先计算固定金额，再按毛额计算百分比）并创建分账项。

按照账户配置的频率（如果分账设置了 immediate: true 则立即执行），通过 PIX 将金额发送给每个收款方。

每次转出都会触发一个 CashOut webhook，返回结果（成功或失败）。

分账类型

FIXED — 固定金额

收款方获得固定金额，与付款总额无关。

{
  "type": "FIXED",
  "value": 10.00
}

金额以雷亚尔为单位，最多 2 位小数：10.00 = R$ 10,00。

PERCENTAGE — 百分比

收款方获得付款毛额（扣除手续费之前）的一定百分比。

{
  "type": "PERCENTAGE",
  "value": 10
}

百分比直接填写：10 = 10%，25.5 = 25.5%。

金额格式

分账金额使用与 transaction.value 字段相同的格式 — 以雷亚尔为单位，最多 2 位小数。

固定金额（FIXED）

雷亚尔金额value 字段中的值
R$ 0,010.01
R$ 1,001.00
R$ 10,0010.00
R$ 100,00100.00
R$ 1.500,501500.50

最小值： 0.01

百分比（PERCENTAGE）

百分比value 字段中的值
1%1
5%5
10%10
25.5%25.5
33.33%33.33
50%50

该值直接表示百分比。 无需乘法换算。

执行频率

频率决定累计的分账何时执行。它由支持团队按账户配置，而不是按交易配置（默认值为 DAILY）。

频率行为
IMMEDIATEPIX-IN 确认后立即执行
HOURLY累计并每小时执行一次
DAILY累计并每天执行一次
WEEKLY累计并每周执行一次

在 HOURLY、DAILY 和 WEEKLY 频率下，多笔交易中发给同一收款方的分账会合并为一笔 PIX-OUT。如果账户配置了最低累计金额，而该收款方的总额低于该金额，则转出会等到下一个周期。

分账中的 immediate 字段

单个分账中的 immediate 字段可以为该特定分账覆盖账户的频率：

{
  "pixKey": "urgente@email.com",
  "pixKeyType": "EMAIL",
  "name": "紧急供应商",
  "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": "订单 #12345 - 电商平台",
    "externalId": "ORDER-12345",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Carlos Oliveira",
    "document": "12345678901"
  },
  "splits": [
    {
      "pixKey": "vendedor@email.com",
      "pixKeyType": "EMAIL",
      "name": "Loja do João",
      "document": "98765432000188",
      "type": "PERCENTAGE",
      "value": 70,
      "immediate": false
    },
    {
      "pixKey": "plataforma@marketplace.com",
      "pixKeyType": "EMAIL",
      "name": "Marketplace Ltda",
      "document": "11222333000144",
      "type": "PERCENTAGE",
      "value": 20,
      "immediate": false
    },
    {
      "pixKey": "12345678901",
      "pixKeyType": "CPF",
      "name": "Entregador Silva",
      "document": "12345678901",
      "type": "FIXED",
      "value": 10.00,
      "immediate": true
    }
  ]
}

付款后的结果（收到 R$ 100,00）：

收款方类型计算金额
卖家70%R$ 100,00 × 70%R$ 70,00
平台20%R$ 100,00 × 20%R$ 20,00
配送员固定R$ 10,00R$ 10,00
合计R$ 100,00

存在平台手续费时，百分比按毛额（扣除手续费之前）计算。手续费和分账都从收到的金额中扣除，剩余部分留在您的账户中。分账的 PIX-OUT 不收取额外手续费。

限制和约束

约束值
每笔交易的最大收款方数量10（如果账户限额更低则以账户为准：SPLIT_MAX_RECIPIENTS_EXCEEDED）
每个分账的最低金额（FIXED）0.01（R$ 0,01）
每个分账的最低百分比0.01（0.01%）
最大小数位数2
百分比总和不超过 100%（SPLIT_PERCENTAGE_EXCEEDS_100）
分账总和 + 手续费不能超过交易金额（SPLIT_EXCEEDS_AMOUNT）

如果固定分账 + 按毛额计算的百分比分账 + 手续费的总和超过交易金额，API 会返回 400 Bad Request，errorCode 为 SPLIT_EXCEEDS_AMOUNT，收款不会被创建。

分账验证错误

在创建收款时均返回 400 Bad Request：

errorCode原因
SPLIT_NOT_CONFIGURED账户未启用分账
SPLIT_MAX_RECIPIENTS_EXCEEDED收款方数量超过账户限额（details.max）
SPLIT_EXCEEDS_AMOUNT分账 + 手续费超过交易金额
SPLIT_PERCENTAGE_EXCEEDS_100百分比总和超过 100%

无金额的静态二维码

对于未设定金额（由付款人填写金额）创建的静态二维码（POST /api/pix/qrcode-static），只允许 PERCENTAGE 类型的分账。FIXED 分账会被拒绝，因为创建时最终金额未知。

Webhooks

PIX-IN 已确认（含分账）

付款确认后，会发送标准的 CashIn webhook。分账会在后台自动处理。

{
  "event": "CashIn",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "CREDIT",
  "transactionId": "12345",
  "externalId": "ORDER-12345",
  "endToEndId": "E00416968202501151030VX5Sx8fIpkY",
  "feeAmount": 0.50,
  "originalAmount": 100.00,
  "finalAmount": 99.50,
  ...
}

分账 PIX-OUT（执行）

每次分账转出都会执行一笔 PIX-OUT 并发送一个 CashOut webhook。这些转出的 externalId 由平台以 split-col-<id> 格式生成，因此不对应您的任何 externalId：

{
  "event": "CashOut",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "67890",
  "externalId": "split-col-321",
  "feeAmount": 0,
  "originalAmount": 70.00,
  "finalAmount": 70.00,
  "counterpart": {
    "name": "Loja do João",
    "document": "98765432000188",
    "bank": { ... }
  },
  ...
}

分账的 CashOut webhook 与常规 Cash-Out webhook 遵循相同的格式和配置。请在控制台的 设置 → Webhooks 中配置您的 webhook。

最佳实践

后续步骤

PIX Cash-In

了解如何创建带分账的收款

Webhooks

配置 webhook 以接收分账通知

查询交易

查询分账交易的状态

PIX Cash-In（收款）

如何生成 PIX 收款并接收付款

PIX Cash-Out（付款）

如何向任意密钥发起 PIX 付款

本页目录

概述使用场景工作原理分账类型FIXED — 固定金额PERCENTAGE — 百分比金额格式固定金额（FIXED）百分比（PERCENTAGE）执行频率分账中的 immediate 字段完整示例场景：3 个收款方的电商平台付款后的结果（收到 R$ 100,00）：限制和约束分账验证错误无金额的静态二维码WebhooksPIX-IN 已确认（含分账）分账 PIX-OUT（执行）最佳实践后续步骤