Split de pagamento: como a divisão automática funciona na API

Na API, o split de pagamento funciona assim: você envia, junto com a cobrança, uma lista de recebedores e quanto cabe a cada um, e o provedor de pagamentos se encarrega de dividir o valor na liquidação, depositando cada parte direto na conta de quem tem direito. O seu sistema não recebe o dinheiro todo para depois repassar. Ele só descreve a divisão.
$ ls ./neste-artigo
- Etapa 1: cadastrar e validar cada recebedor
- Etapa 2: escrever a regra de divisão sem perder centavos
- Etapa 3: criar a cobrança com chave de idempotência
- Etapa 4: liquidação, agenda de recebíveis e o que muda no parcelado
- Etapa 5: webhooks e conciliação, a parte que ninguém documenta direito
- Etapa 6: estorno parcial e chargeback sem quebrar o caixa de ninguém
- Onde o split aparece fora do e-commerce
Parece simples no exemplo de documentação, com uma venda de R$ 100 dividida em 90 e 10. Os problemas aparecem nas bordas: centavos que não fecham, compra parcelada, estorno parcial, chargeback três meses depois e recebedor com cadastro pendente.
Em poucas palavras: o split exige quatro decisões antes da primeira linha de código. Quem são os recebedores e como eles são validados, qual regra de divisão vale, quem paga a taxa da transação e quem assume o prejuízo de um estorno ou chargeback.
Etapa 1: cadastrar e validar cada recebedor
Todo recebedor de um split precisa existir no provedor antes da primeira venda. Na maioria das APIs, isso significa criar uma subconta ou um “recipient”, com dados cadastrais, conta bancária para repasse e documentos para validação de identidade.
Essa validação não é burocracia opcional. Como o dinheiro vai direto para a conta de terceiros, o provedor precisa aplicar KYC para pessoas físicas e KYB (know your business) para empresas, cumprindo regras de prevenção à lavagem de dinheiro. Plataformas do mercado de crédito, como a INFINITOCred, automatizam essa etapa no cadastro de clientes e parceiros justamente porque um recebedor sem validação trava o repasse inteiro.
Na prática, crie o recebedor no momento do onboarding do parceiro, guarde o identificador retornado pela API e trate o status. Recebedor “pendente” ou “em análise” não deveria aparecer como opção ativa no seu sistema.

Etapa 2: escrever a regra de divisão sem perder centavos
A regra de divisão define quanto cada recebedor leva, em valor fixo ou percentual, e pode ser diferente em cada cobrança. O erro clássico está no arredondamento: 33,33% de R$ 100,00 dá R$ 33,333…, e três partes arredondadas somam R$ 99,99.
Duas práticas evitam a dor de cabeça:
- Trabalhe sempre em centavos inteiros. R$ 100,00 vira 10000. Nada de ponto flutuante em cálculo financeiro.
- Defina quem leva o resto. Calcule as partes, some, e jogue a diferença (normalmente 1 ou 2 centavos) num recebedor fixo, em geral a própria plataforma.
Um corpo de requisição genérico, ilustrativo e sem seguir um provedor específico, fica assim:
{ “valor”: 10000, “metodo”: “cartao_credito”, “parcelas”: 3, “split”: [ { “recebedor”: “rec_parceiro_42”, “tipo”: “percentual”, “valor”: 90, “assume_chargeback”: true, “paga_taxa”: true }, { “recebedor”: “rec_plataforma”, “tipo”: “percentual”, “valor”: 10, “recebe_resto”: true } ] }
Repare nos campos de responsabilidade. Cada provedor usa nomes próprios, mas quase todos pedem que você diga quem paga a taxa de processamento e quem responde por estornos.
Etapa 3: criar a cobrança com chave de idempotência
A cobrança com split é criada numa única chamada, e essa chamada precisa ser idempotente. Se a conexão cair depois que o provedor processou o pedido, mas antes de a resposta chegar, o seu sistema vai tentar de novo. Sem uma chave de idempotência, você cria duas cobranças e divide o mesmo pagamento duas vezes.
Gere um identificador único por pedido (o número do pedido no seu banco de dados serve) e envie no cabeçalho indicado pelo provedor. Na segunda tentativa, a API devolve a cobrança original em vez de criar outra.
Etapa 4: liquidação, agenda de recebíveis e o que muda no parcelado
A divisão de fato acontece na liquidação, quando o dinheiro sai do arranjo de pagamento e chega às contas. No Pix, isso é imediato. No cartão de crédito, o valor segue a agenda de recebíveis: cada parcela é liquidada no seu mês, e o split é aplicado parcela por parcela.
| Meio de pagamento | Quando cada recebedor vê o dinheiro | Ponto de atenção no split |
|---|---|---|
| Pix | Na confirmação do pagamento | Devolução pode ser pedida depois; defina de quem sai |
| Boleto | Após a compensação | Pagamento a menor ou em atraso altera as partes |
| Cartão à vista | Conforme o prazo contratado com o provedor | Chargeback pode chegar meses depois |
| Cartão parcelado | Parcela a parcela, mês a mês | Antecipação muda taxas de cada recebedor |
O enquadramento regulatório também pesa. A Lei nº 12.865/2013 estruturou os arranjos e as instituições de pagamento no Brasil, e o Banco Central passou a exigir que os recebíveis de cartão circulem pela liquidação centralizada. Na prática, isso favorece que o dinheiro de cada recebedor chegue a ele pela própria liquidação, em vez de passar pela conta da plataforma. As regras gerais estão na página de arranjos de pagamento do Banco Central.
Etapa 5: webhooks e conciliação, a parte que ninguém documenta direito
O provedor avisa por webhook cada mudança de estado: cobrança paga, parcela liquidada, repasse feito, estorno, contestação. O seu sistema precisa ouvir esses eventos e atualizar o saldo de cada recebedor, sem depender de consulta manual.
- Valide a assinatura do webhook. Qualquer um pode enviar um POST para a sua URL. Só confie em eventos assinados pelo provedor.
- Trate eventos fora de ordem. O aviso de “repasse feito” pode chegar antes do “pagamento confirmado”. Use o estado mais avançado.
- Registre o evento antes de processar. Se o processamento falhar, você reprocessa a partir do registro, sem perder nada.
- Concilie todo dia. Compare o extrato de repasses do provedor com o que o seu sistema calculou. Diferença de centavo hoje vira diferença de milhares em um ano.
Atalhos nessa etapa costumam virar o tipo de dívida técnica que o portal descreve em como saber quando o débito técnico está saindo caro.
Etapa 6: estorno parcial e chargeback sem quebrar o caixa de ninguém
O estorno é onde o split mais gera conflito, porque o dinheiro já foi dividido. Se uma venda de R$ 100 foi repartida em 90 e 10 e o cliente devolve metade do produto, quem devolve os R$ 50: o parceiro, a plataforma ou os dois, na proporção?
A maioria dos provedores aceita três modelos: estorno proporcional entre todos os recebedores, estorno debitado de um recebedor específico ou regra definida por cobrança. Escolha um, escreva no contrato com os parceiros e reflita no campo de responsabilidade da requisição. Chargeback segue a mesma lógica, mas com um agravante: ele pode chegar depois que o parceiro já sacou o dinheiro, e o provedor vai debitar de quem foi marcado como responsável.
Uma proteção comum é manter uma parte do saldo do parceiro retida por alguns dias, como reserva para contestações. Use com transparência, porque reter sem avisar é a forma mais rápida de perder parceiros.
Onde o split aparece fora do e-commerce
Marketplace é o exemplo óbvio, mas o mesmo mecanismo serve a franquias, plataformas de serviço, aplicativos de entrega e redes de vendedores que ganham comissão. No mercado de crédito, por exemplo, redes de correspondentes usam a divisão automática para pagar comissões de licenciados e franqueados sem planilha nem transferência manual.
O Infinito PAY, gateway da INFINITOCred, a empresa de Alex Araripe, é um exemplo desse uso: o gateway com split automático distribui as comissões da rede de parceiros no momento do recebimento. Do lado técnico, o desenho é o mesmo descrito nas etapas acima, com um recebedor por licenciado e a regra de comissão aplicada a cada venda.
Quem quiser ver como uma operação desse tipo apresenta o fluxo ao parceiro pode olhar a plataforma da INFINITOCred, voltada à rede de correspondentes.
Antes de integrar qualquer provedor, faça um teste no ambiente de sandbox com os quatro cenários que mais quebram: divisão com resto de centavos, venda parcelada em 12 vezes, estorno parcial e chargeback de uma venda já repassada. Se a sua integração passar nos quatro, ela aguenta o dia a dia.




