Para o negócio: se o contrato com o vendedor diz “2% sobre o valor da venda”, o percentual enviado no split fica um pouco acima de 2%. A diferença existe porque o split incide sobre um valor menor (o líquido). O objetivo é que o vendedor pague os 2% combinados sobre o bruto. Se o vendedor antecipar os recebíveis, a base do split diminui e a comissão recebida fica menor que o alvo (veja Cuidados).
Quando usar
- A sua plataforma cobra uma comissão percentual sobre o valor bruto de cada venda das subcontas.
- Você quer que a comissão recebida por split fique alinhada ao valor do contrato.
- Você mostra ao vendedor um extrato com “valor da venda, taxa da plataforma e valor a receber”.
O problema
Com a base líquida, que é o padrão, o split é calculado depois da dedução da taxa transacional da Finvia sobre a cobrança:- taxa percentual transacional, que depende do método, da bandeira e do número de parcelas;
- taxa fixa por transação (por exemplo, R$ 0,40).
percentage: 2, a plataforma recebe 2% de R$ 94,60, ou seja, R$ 1,89. O combinado eram R$ 2,00.
A taxa de antecipação só reduz a base do split quando o originador antecipa o recebível. Sem antecipação, o repasse é o percentual sobre o valor líquido da taxa transacional. Calcular o split sobre o valor bruto é uma configuração de conta feita pela Finvia, sob consulta; com ela, nenhum ajuste desta página é necessário.
De onde vêm as taxas
As taxas que entram no cálculo (f e c) não devem ficar fixas no código. Elas são da própria subconta e podem variar por método de pagamento, moeda, bandeira e número de parcelas. Consulte direto na API:
fees como uma lista plana. Para chegar à taxa transacional efetiva:
1
Filtre a linha transacional
feeType tx_spread, com paymentMethod e currencyCode iguais aos da cobrança.2
Escolha a bandeira
No cartão, use a linha com
brand igual à bandeira do cartão. Se ela não existir, use a linha com brand: null.3
Leia o percentual e a taxa fixa
O percentual é
definition.percentages[parcelas - 1] (índice 0 = à vista). A taxa fixa é definition.fixed, por transação.A fórmula
Para que o split entregue o valor que a plataforma quer cobrar sobre o bruto:Exemplo passo a passo
Venda de R$ 100,00 em 2x, com taxa transacional de 5% para 2x e taxa fixa de R$ 0,40. A plataforma quer cobrar 2% sobre o bruto. O desenho abaixo mostra a cascata deste exemplo: do valor bruto ao líquido, do líquido ao percentual de split, e quanto fica com cada um. Conferência: R$ 5,40 da Finvia + R$ 2,00 da plataforma + R$ 92,60 do vendedor somam os R$ 100,00 da venda, quando não há antecipação.1
Leia a taxa transacional
Na linha
tx_spread da bandeira, percentages[1] = 5, então f = 0,05. A taxa fixa é c = 0,40.2
Calcule o valor líquido
L = 100 × (1 − 0,05) − 0,40 = 95 − 0,40 = R$ 94,60.3
Defina o valor que a plataforma quer receber
2% sobre o bruto:
0,02 × 100 = R$ 2,00.4
Calcule o percentual de split
s = 2,00 ÷ 94,60 = 2,1142%. Na cobrança, envie "percentage": 2.1142.5
Confira
2,1142% × 94,60 = R$ 2,00. O vendedor (subconta) fica com 94,60 − 2,00 = R$ 92,60, que é o mesmo que 100 − 5 − 0,40 − 2.A conta fecha quando a soma “taxa transacional da Finvia + valor da plataforma + valor do vendedor” é igual ao valor bruto. No exemplo: R$ 5,40 + R$ 2,00 + R$ 92,60 = R$ 100,00. Isso vale quando o vendedor não antecipa.
Tabela de referência
A tabela abaixo funciona como uma calculadora pronta para conferência, sem antecipação. O primeiro caso é o exemplo acima. Os outros três usam taxas ilustrativas. Na sua integração, use sempre as taxas reais da subconta.
Como cada linha foi calculada:
- Pix à vista:
L = 200 × (1 − 0,015) − 0 = 197,00.s = 6,00 ÷ 197,00 = 3,0457%. Conferência: R$ 3,00 + R$ 6,00 + R$ 191,00 = R$ 200,00. - Cartão Visa 6x: na linha
tx_spreadda bandeira Visa,percentages[5]= 5,49.f = 0,0549.L = 600 × 0,9451 − 0,50 = 566,56.s = 12,00 ÷ 566,56 = 2,1180%. Conferência: R$ 33,44 + R$ 12,00 + R$ 554,56 = R$ 600,00. - Cartão Visa à vista com 5%:
percentages[0]= 2,99.L = 300 × 0,9701 − 0,50 = 290,53.s = 15,00 ÷ 290,53 = 5,1630%. Conferência: R$ 9,47 + R$ 15,00 + R$ 275,53 = R$ 300,00.
Implementação
A conversão em código recebe as taxas em fração e devolve o percentual de split:TypeScript
f e c a partir da resposta de fees-info, escolhendo a linha transacional certa por método, moeda e bandeira e a parcela desejada:
TypeScript
consultarFeesInfo de Taxas da subconta:
TypeScript
Cuidados
Enquanto a cobrança não liquida, osplitAmount de GET /v1/charges/{id} mostra uma simulação do valor com antecipação, menor que o valor da tabela. Depois que as parcelas liquidam sem antecipação, ele passa a mostrar o percentual sobre o valor líquido. Veja Split de pagamentos.
Na conciliação, compare o valor que a plataforma recebeu com o valor alvo (p × V). A diferença mostra quanto a antecipação ou uma mudança de taxa afastou o resultado do cálculo.
O percentual de split carrega arredondamento (ex.:
2,1142%). Mantenha as casas decimais do percentual e arredonde para 2 casas só o valor resultante em reais, no fechamento, para evitar diferenças de centavos em valores altos. No caso “Cartão Visa 6x”, por exemplo, arredondar o percentual para 2,12% daria 2,12% × 566,56 = R$ 12,01, um centavo a mais que os R$ 12,00 combinados. Com 2,1180%, o resultado é R$ 12,00.Erros comuns
Perguntas frequentes
Por que o percentual de split é maior que a minha comissão?
Por que o percentual de split é maior que a minha comissão?
Porque ele incide sobre o valor líquido, que é menor que o bruto. Para chegar ao mesmo valor em reais, o percentual sobre a base menor precisa ser maior.
Preciso recalcular para cada venda?
Preciso recalcular para cada venda?
Sim, sempre que método, bandeira, parcelas ou valor mudarem. A taxa fixa pesa mais em vendas pequenas e o percentual transacional muda com as parcelas, então o percentual de split muda junto.
Posso usar o split padrão da conta com comissão sobre o bruto?
Posso usar o split padrão da conta com comissão sobre o bruto?
A regra padrão aplica um percentual fixo sobre o líquido de todas as vendas. Se a comissão é sobre o bruto e as taxas variam por venda, o valor recebido também varia. Para valor exato, envie o
split calculado em cada cobrança.E se o vendedor antecipar os recebíveis?
E se o vendedor antecipar os recebíveis?
Com a base líquida, o split é recalculado sobre o valor já descontada a taxa de antecipação, e a plataforma recebe proporcionalmente menos. A base bruta e a opção de a master absorver a taxa de antecipação das subcontas existem sob consulta.
Como confiro se o cálculo deu certo?
Como confiro se o cálculo deu certo?
Consulte a cobrança em
GET /v1/charges/{id}: a lista splits traz splitPercentage e referenceAmount de cada recebedor. Depois da liquidação, compare o valor recebido com o valor alvo. A soma da taxa transacional, da parte da plataforma e da parte do vendedor precisa bater com o valor bruto quando não há antecipação.Como testar
No roteiro de homologação, o cenário SPL-05 pede a conferência desplitPercentage e da coerência com a base de cálculo (referenceAmount) em GET /v1/charges/{id}. Enquanto a cobrança não liquida, splitAmount pode vir menor que o valor da tabela, porque simula uma antecipação. Use a tabela de referência desta página para montar casos de teste com valores conhecidos. O SPL-06 cobre Pix e cartão parcelado.
Veja também
Split de pagamentos
Regras, relações permitidas e exemplos de requisição.
Taxas da subconta
Como ler a resposta de
fees-info.Taxas e dados (referência)
Referência completa da rota de taxas.
Marketplace e PSP
Caso de uso com comissão por split.

