Skip to main content
O split divide automaticamente o valor de uma venda entre contas do mesmo grupo Connect (a conta master e as subcontas dela). A plataforma recebe a comissão dela, o vendedor recebe a parte dele, e um parceiro pode receber uma fatia, tudo na mesma cobrança e sem transferências manuais depois da venda.

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).
Para PSPs, o split é obrigatório: toda transação de PSP precisa ter split entre a conta master (PSP) e a subconta (lojista), e split de 100% para o PSP não é permitido. Veja as Regras de credenciamento.

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 lista split: 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

O percentual é aplicado sobre o valor líquido, que é o valor da venda menos as taxas da Finvia. Se a sua plataforma cobra 2% sobre o valor bruto e você envia percentage: 2, recebe menos do que espera. Calcule o percentual correto com a fórmula de Cálculo de split.
Para que a venda fique vinculada à subconta que vendeu, crie a cobrança com a chave secreta da subconta originadora, obtida em GET /v1/submerchants/{id}/api-keys. Se a cobrança for criada com a chave da master, a master é a originadora.

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 split seguem 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 campo split 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.
Para o desenvolvedor: use o split via API quando o percentual muda de venda para venda (por exemplo, comissão diferente por categoria de produto ou por campanha). Calcule o percentual no seu servidor, com as taxas reais da subconta, antes de criar a cobrança.

Exemplos

Os exemplos usam três contas do mesmo grupo Connect. Substitua pelos id 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.
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 campo split é 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 em GET /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.
Com base 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

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.
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.
Substitui. A configuração enviada na cobrança vale só para ela e prevalece sobre a regra padrão.
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.
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.