Split de Pagamentos
Visão Geral
O Split de Pagamentos permite dividir automaticamente o valor de um PIX recebido (Cash-In) entre múltiplos destinatários. Quando um pagamento é confirmado, o sistema calcula a parte de cada destinatário e executa os envios (PIX-OUT) automaticamente.
O split é configurado no momento da criação da cobrança (Cash-In ou QR Code Estático). Não é possível adicionar splits a uma transação já criada.
O split precisa estar habilitado na sua conta antes do uso. Sem essa habilitação, uma cobrança enviada com splits é recusada com 400 e errorCode SPLIT_NOT_CONFIGURED. A habilitação, a frequência de execução, o valor mínimo acumulado e o limite de destinatários por transação são definidos por conta pelo suporte (suporte@fypay.me [A DEFINIR]); não há endpoint público para alterá-los.
Casos de Uso
Marketplace
Dividir automaticamente o pagamento entre vendedor e plataforma (comissão).
Sociedades
Distribuir receita entre sócios com percentuais pré-definidos.
Franquias
Repasse automático de royalties e taxas para a franqueadora.
Prestadores de Serviço
Repasse automático ao prestador com retenção de taxa da plataforma.
Como Funciona
Ao gerar um PIX Cash-In, inclua o array splits com os destinatários e seus valores (fixo ou percentual).
Quando o pagador efetua o PIX, o webhook CashIn é enviado com status CONFIRMED.
O sistema calcula o valor de cada destinatário (fixos primeiro, depois percentuais sobre o valor bruto) e cria os itens de split.
Conforme a frequência configurada na conta (ou na hora, se o split tiver immediate: true), os valores são enviados via PIX para cada destinatário.
Para cada envio, um webhook CashOut é disparado com o resultado (sucesso ou falha).
Tipos de Split
FIXED — Valor Fixo
O destinatário recebe um valor fixo independente do valor total do pagamento.
{
"type": "FIXED",
"value": 10.00
}O valor é em reais com até 2 casas decimais: 10.00 = R$ 10,00.
PERCENTAGE — Percentual
O destinatário recebe um percentual do valor bruto do pagamento (antes das taxas).
{
"type": "PERCENTAGE",
"value": 10
}O percentual é informado diretamente: 10 = 10%, 25.5 = 25,5%.
Formato de Valores
Os valores de split usam o mesmo formato do campo transaction.value — em reais com até 2 casas decimais.
Valores Fixos (FIXED)
| Valor em Reais | Valor no Campo 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 |
Mínimo: 0.01
Percentuais (PERCENTAGE)
| Percentual | Valor no Campo value |
|---|---|
| 1% | 1 |
| 5% | 5 |
| 10% | 10 |
| 25,5% | 25.5 |
| 33,33% | 33.33 |
| 50% | 50 |
O valor representa o percentual diretamente. Sem multiplicação.
Frequências de Execução
A frequência determina quando os splits acumulados são executados. Ela é configurada por conta pelo suporte, não por transação (o padrão é DAILY).
| Frequência | Comportamento |
|---|---|
IMMEDIATE | Executado imediatamente após a confirmação do PIX-IN |
HOURLY | Acumulado e executado a cada hora |
DAILY | Acumulado e executado uma vez por dia |
WEEKLY | Acumulado e executado uma vez por semana |
Nas frequências HOURLY, DAILY e WEEKLY, os splits de múltiplas transações para o mesmo destinatário são agrupados em um único PIX-OUT. Se a conta tiver um valor mínimo acumulado configurado e o total do destinatário ficar abaixo dele, o envio aguarda o próximo ciclo.
Campo immediate no Split
O campo immediate no split individual permite sobrescrever a frequência da conta para aquele split específico:
{
"pixKey": "urgente@email.com",
"pixKeyType": "EMAIL",
"name": "Fornecedor Urgente",
"document": "12345678000199",
"type": "FIXED",
"value": 50.00,
"immediate": true
}Quando immediate: true, o split é executado imediatamente após a confirmação do PIX-IN, mesmo que a conta esteja configurada com frequência DAILY.
Exemplo Completo
Cenário: Marketplace com 3 destinatários
Um marketplace recebe R$ 100,00 de um cliente. O valor deve ser dividido:
- Vendedor: 70% do valor
- Plataforma: 20% do valor
- Entregador: R$ 10,00 fixo
{
"transaction": {
"value": 100.00,
"description": "Pedido #12345 - Marketplace",
"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
}
]
}Resultado após o pagamento (R$ 100,00 recebido):
| Destinatário | Tipo | Cálculo | Valor |
|---|---|---|---|
| Vendedor | 70% | R$ 100,00 × 70% | R$ 70,00 |
| Plataforma | 20% | R$ 100,00 × 20% | R$ 20,00 |
| Entregador | Fixo | R$ 10,00 | R$ 10,00 |
| Total | R$ 100,00 |
Quando há taxa da plataforma, o percentual é calculado sobre o valor bruto (antes da taxa). A taxa e os splits saem do valor recebido, e o que sobra fica na sua conta. Os PIX-OUT de split não têm taxa adicional.
Limites e Restrições
| Restrição | Valor |
|---|---|
| Máximo de destinatários por transação | 10 (ou menos, se o limite da conta for menor: SPLIT_MAX_RECIPIENTS_EXCEEDED) |
| Valor mínimo por split (FIXED) | 0.01 (R$ 0,01) |
| Percentual mínimo por split | 0.01 (0,01%) |
| Máximo de casas decimais | 2 |
| Soma dos percentuais | Até 100% (SPLIT_PERCENTAGE_EXCEEDS_100) |
| Soma dos splits + taxa | Não pode exceder o valor da transação (SPLIT_EXCEEDS_AMOUNT) |
Se a soma dos splits fixos + percentuais sobre o valor bruto + taxa exceder o valor da transação, a API retorna 400 Bad Request com errorCode SPLIT_EXCEEDS_AMOUNT e a cobrança não é criada.
Erros de validação do split
Todos retornam 400 Bad Request na criação da cobrança:
errorCode | Causa |
|---|---|
SPLIT_NOT_CONFIGURED | O split não está habilitado na conta |
SPLIT_MAX_RECIPIENTS_EXCEEDED | Mais destinatários que o limite da conta (details.max) |
SPLIT_EXCEEDS_AMOUNT | Splits + taxa excedem o valor da transação |
SPLIT_PERCENTAGE_EXCEEDS_100 | A soma dos percentuais passa de 100% |
QR Code Estático sem Valor
Para QR Codes estáticos (POST /api/pix/qrcode-static) criados sem valor definido (o pagador informa o valor), apenas splits do tipo PERCENTAGE são permitidos. Splits FIXED são rejeitados, pois o valor final não é conhecido no momento da criação.
Webhooks
PIX-IN Confirmado (com splits)
Quando o pagamento é confirmado, o webhook CashIn padrão é enviado. Os splits são processados automaticamente em background.
{
"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 do Split (execução)
Para cada envio de split, um PIX-OUT é executado e um webhook CashOut é enviado. O externalId desses envios é gerado pela plataforma no formato split-col-<id>, então não corresponde a nenhum externalId seu:
{
"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": { ... }
},
...
}Os webhooks de CashOut dos splits seguem o mesmo formato e configuração dos webhooks de Cash-Out normais. Configure seus webhooks em Configurações → Webhooks no painel.