Quando usar
Não use o split para dividir valores com empresas fora do seu grupo Connect: todas as contas participantes precisam estar no mesmo grupo. Para cadastrar um novo participante, crie uma subconta (Subcontas e KYC).
Como funciona
O desenho abaixo mostra como o valor de uma venda é dividido, usando o exemplo “Dois recebedores” desta página: a plataforma fica com 5% do líquido, o parceiro com 10% e o vendedor com o restante. O valor de cada participante é calculado na criação da cobrança e dividido igualmente entre as parcelas. O vendedor não entra na listasplit: como originador, ele fica com o que sobra.
1
Defina quem origina a venda
O originador é a conta cuja chave secreta cria a cobrança. Em um marketplace, normalmente é a subconta do vendedor.
2
Defina os recebedores e percentuais
Cada recebedor é um
merchantId com um percentage entre 0.01 e 100. A soma não pode passar de 100%.3
Crie a cobrança
Com regra de split padrão configurada na conta, basta criar a cobrança. Para uma divisão específica daquela venda, envie o campo
split em POST /v1/charges.4
O valor de cada participante é calculado
Na criação da cobrança, a Finvia desconta a taxa transacional (fixa + percentual) do valor bruto. Sobre o valor líquido que sobra, cada recebedor fica com o percentual dele. O restante fica com o originador. O valor de cada participante é dividido igualmente entre as parcelas.
5
Repasse na liquidação
Cada parte é repassada parcela a parcela, quando o recebível do originador é liquidado: no cartão, a cada 30 dias por parcela; no Pix, logo após a confirmação do pagamento. Veja a seção “Liquidação e repasse”, abaixo.
Regras de negócio
Relações permitidas
Split padrão da conta
No painel da Finvia, na gestão de subcontas, você configura a regra de split padrão: os participantes e o percentual de cada um.- A configuração vira o padrão daquela conta: todas as cobranças que ela originar sem o campo
splitseguem a regra. - A regra vale por moeda e por meio de pagamento (por exemplo, um percentual no Pix e outro no cartão).
- Uma subconta sem regra própria usa a regra padrão definida pela master.
Para o negócio: o split padrão é indicado quando a regra comercial é fixa por vendedor, como uma comissão contratual. A sua equipe configura uma vez e as vendas seguintes já saem divididas, mesmo que a integração não envie o campo
split.Split por cobrança via API
Envie o camposplit no corpo de POST /v1/charges:
A configuração enviada pela API vale somente para aquela cobrança e prevalece sobre a regra padrão da conta. O split vale para cobranças criadas por
POST /v1/charges; as cobranças recorrentes de assinatura não recebem split.
Em validação (V-64): há um erro conhecido no split de cobranças com 3D Secure gerenciado. Até a correção, não combine split com 3DS gerenciado.
Exemplos
Os exemplos usam três contas do mesmo grupo Connect. Substitua pelosid reais.
A variável
SUBCONTA_SECRET_KEY guarda a chave secreta da subconta do vendedor, e FINVIA_API_KEY guarda a chave secreta da conta master.
- Comissão da plataforma
- Dois recebedores
- Subconta para subconta
- Master para subconta
A subconta do vendedor vende um produto de R$ 100,00 por Pix e a plataforma (conta master,
36OO3bcGjhPjjF3tzrqOGcmQuKo) recebe a comissão. A plataforma cobra 2% sobre o bruto. As taxas deste exemplo são ilustrativas: Pix com 1,5% e sem taxa fixa. O líquido é R$ 98,50 e o percentual sobre o líquido fica em 2.0305, que entrega R$ 2,00 à plataforma (veja a fórmula em Cálculo de split). Na sua integração, use as taxas reais da subconta.Exemplo em Node.js
Node.js
Split em Pix e em cartão parcelado
O camposplit é o mesmo para Pix e para cartão. A diferença está nas taxas: cada método, bandeira e número de parcelas pode ter uma taxa diferente, e isso muda o valor líquido. Como o split incide sobre o líquido, o mesmo percentual entrega valores diferentes em uma venda Pix e em uma venda em 6x de mesmo valor bruto.
Se a sua comissão é definida sobre o valor bruto, calcule o percentual para cada combinação de método e parcelas a partir das taxas reais da subconta (Taxas da subconta e Cálculo de split).
Liquidação e repasse
O valor de cada participante é calculado na criação da cobrança e repassado a cada parcela, quando o recebível do originador é liquidado: no cartão, a cada 30 dias por parcela (D+30, D+60…); no Pix, logo após a confirmação do pagamento. O repasse sai do saldo disponível do originador e entra no saldo disponível do recebedor. Se o originador antecipar, o repasse acontece na antecipação e é calculado sobre o valor já descontada a taxa de antecipação. A parte correspondente à reserva financeira do originador é repassada quando a reserva é liberada. O desenho abaixo mostra quando a parte do recebedor sai do saldo do originador e chega ao saldo dele, no Pix, no cartão parcelado e na antecipação. Retenção do recebível pela Finvia, reserva financeira, bloqueio de saldo do recebedor e estorno mudam esse caminho como descrito na tabela a seguir.Para o negócio: duas opções são configuradas pela Finvia, sob consulta: calcular o split sobre o valor bruto (com base bruta, a antecipação não muda o valor do split) e a conta master absorver a taxa de antecipação das subcontas. Fale com o seu contato comercial se precisar de alguma delas.
Consulte os valores divididos
Depois da venda, consulte a cobrança emGET /v1/charges/{id}. A resposta traz a lista splits, um item por recebedor. Ela não aparece na listagem de cobranças nem na resposta de criação.
cURL
No POST o campo é
split (singular), com merchantId e percentage. Na consulta é splits (plural), com os nomes acima. Se a cobrança foi criada sem split, splits vem preenchido com a regra padrão da conta.
O que splitAmount mostra com base net:
- Enquanto há parcelas a liquidar e nenhuma antecipação concluída: uma simulação do valor que o recebedor teria se o originador antecipasse, já descontada a taxa de antecipação estimada. Não é o valor que será repassado.
- Depois que as parcelas liquidam sem antecipação: o percentual sobre o valor líquido, sem desconto de antecipação.
- Depois de uma antecipação concluída: o valor efetivamente destinado, recalculado sobre o valor antecipado.
gross, splitAmount é sempre o percentual × valor bruto. O split pode aparecer também em cobrança recusada, mas o repasse só acontece quando a cobrança é paga.
Para acompanhar o total recebido por split em cada subconta, GET /v1/submerchants/{id} traz o objeto metrics, com splitBalance (total recebido por split, em reais) e splitRate (percentual médio de split aplicado à subconta).
Erros comuns
Perguntas frequentes
Se eu não enviar split na cobrança, o que acontece?
Se eu não enviar split na cobrança, o que acontece?
Vale a regra padrão da conta originadora para aquela moeda e método. Uma subconta sem regra própria usa a regra padrão da master. Sem nenhuma regra, a venda inteira (líquida de taxas) fica com o originador.
Posso mandar 100% para outra conta?
Posso mandar 100% para outra conta?
Tecnicamente, o máximo por recebedor é
100, e a soma não pode passar de 100%. Para PSPs, a regra é outra: split de 100% para o PSP não é permitido, e toda transação precisa dividir o valor entre a master e a subconta do lojista.O split da API substitui a regra padrão ou soma com ela?
O split da API substitui a regra padrão ou soma com ela?
Substitui. A configuração enviada na cobrança vale só para ela e prevalece sobre a regra padrão.
Quando o recebedor vê o dinheiro?
Quando o recebedor vê o dinheiro?
Na liquidação de cada parcela do originador: no cartão, em D+30 para a 1ª parcela, D+60 para a 2ª e assim por diante; no Pix, no mesmo dia, logo após a confirmação. Se o originador antecipar, o repasse acontece na antecipação.
Quem paga as taxas da Finvia na venda com split?
Quem paga as taxas da Finvia na venda com split?
Com a base líquida (o padrão), a taxa transacional é descontada antes da divisão, e todos os participantes recebem o percentual deles sobre o que sobra. Se o originador antecipar, a taxa de antecipação também reduz a base. A base bruta e a opção de a master absorver a taxa de antecipação das subcontas existem sob consulta.
Como testar
Cenários do roteiro de homologação, seção de cobrança com split:Veja também
Cálculo de split
Como transformar uma comissão sobre o bruto no percentual correto.
Taxas da subconta
De onde vêm as taxas que definem o valor líquido.
Criar cobrança
Referência completa, incluindo o campo
split.Marketplace e PSP
Caso de uso completo com subcontas e split.

