Skip to main content
Quando uma plataforma integrada ao Connect (conta master e subcontas) cobra uma taxa própria sobre as vendas das subcontas e recebe essa taxa por split, aparece uma diferença de base de cálculo. Por padrão, a Finvia aplica o split sobre o valor líquido, depois de descontar a taxa transacional da venda. A plataforma, em geral, define a comissão sobre o valor bruto. Por isso o percentual de split precisa ser ajustado para chegar ao valor combinado.
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”.
Se a sua comissão já é definida sobre o valor líquido (depois das taxas da Finvia), envie o percentual direto, sem ajuste.

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).
O que sobra é o valor líquido, e é sobre ele que o percentual de split é aplicado. A plataforma calcula a taxa dela sobre o valor bruto da venda. Se você usar o mesmo percentual nos dois lados, a plataforma recebe menos, porque a base do split (líquido) é menor que a base da cobrança (bruto). Exemplo rápido: venda de R$ 100,00 com R$ 5,40 de taxa transacional. Com 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:
A rota devolve as taxas efetivas da subconta: na cobrança, a API usa só as taxas da própria conta que cobra. Os detalhes estão em Taxas da subconta. A resposta traz 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.
Se fees vier vazio, ou sem linha para o método e a moeda da venda, a subconta não tem taxa configurada para essa combinação, e as cobranças dela são recusadas com 422 Fees not configured. Não calcule com taxa zero nem com as taxas da master: fale com o suporte da Finvia.

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_spread da 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.
Os percentuais de split estão arredondados para 4 casas decimais. As taxas da tabela são ilustrativas.

Implementação

A conversão em código recebe as taxas em fração e devolve o percentual de split:
TypeScript
E para obter 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
Juntando as duas funções no seu servidor, antes de criar a cobrança. Este bloco continua os dois anteriores e usa a função consultarFeesInfo de Taxas da subconta:
TypeScript

Cuidados

Antecipação pelo originador: só o originador (normalmente a subconta do vendedor) antecipa o recebível. Quando ele antecipa, de forma manual ou automática, o split é recalculado sobre o valor já descontada a taxa de antecipação, e a plataforma passa a receber proporcionalmente menos que o valor alvo. A taxa de antecipação de fees-info é mensal: só percentages[0] é usado, multiplicado pelo número de meses até o vencimento de cada parcela (mínimo de 1 mês). Por isso o efeito é maior em vendas com mais parcelas. A opção de a conta master absorver a taxa de antecipação das subcontas existe sob consulta.
Enquanto a cobrança não liquida, o splitAmount 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

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.
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.
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.
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.
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 de splitPercentage 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.