Skip to main content
A rota GET /v1/fast-connect/sub-accounts/{id}/fees-info devolve as taxas de uma subconta (transacionais e de antecipação) e os dados cadastrais básicos dela: razão social e CNPJ. Com essas informações, a sua plataforma mostra ao lojista quanto ele paga em cada forma de pagamento e calcula o percentual de split correto para a sua comissão.

Quando usar

Para o negócio: as taxas de cada subconta podem ser diferentes por método de pagamento, bandeira e número de parcelas. Consultar a rota evita que a sua plataforma mostre ao vendedor uma tabela desatualizada ou calcule comissões com taxas erradas.

Como funciona

1

Autentique

Com a chave secreta (sk_, via Basic) da conta master ou da subconta.
2

Chame a rota

Como conta master, informe o id da subconta no caminho. Como subconta, a rota devolve sempre os dados da própria subconta.
3

Leia a resposta

O objeto merchant traz os dados cadastrais. A lista fees traz cada linha de taxa como está configurada.
4

Escolha a linha certa

Filtre por tipo, método, moeda e bandeira, e pegue o percentual da parcela desejada. A rota não faz esse trabalho por você.

De onde vêm as taxas da subconta

Na criação, a subconta recebe uma cópia das taxas vigentes da conta master. Depois disso, as taxas da subconta são independentes:
  • alterar as taxas da master não muda as das subcontas já criadas;
  • a Finvia pode replicar uma alteração para as subcontas por operação interna; peça ao suporte se precisar;
  • se a subconta chegar à pré-aprovação ainda sem nenhuma taxa (por exemplo, porque a master não tinha taxas quando ela foi criada), ela recebe uma cópia das taxas padrão da plataforma naquele momento.
Na cobrança, a API usa só as taxas da própria conta que cobra, sem consultar a master nem as taxas padrão. Por isso, o que esta rota devolve já são as taxas efetivas da subconta.
Se fees vier vazio, ou sem linha para o método e a moeda de uma cobrança, as cobranças dessa combinação são recusadas com 422 Fees not configured. Não use as taxas da master no lugar nem trate a lista vazia como taxa zero: acione o suporte da Finvia para configurar as taxas.
fees-info não traz a reserva financeira nem a taxa de saque da subconta. O contrato público também não tem rota para a master ajustar as taxas de uma subconta.

Comportamento por conta autenticada

O resultado depende de qual conta está autenticada, além do id informado:
Para o desenvolvedor: se a sua aplicação chama a rota com a chave da subconta, qualquer valor no id devolve os dados da própria subconta. Isso evita que uma subconta veja as taxas de outra. Com a chave da master, o id é obrigatório e precisa ser de uma subconta vinculada.

Estrutura da resposta

Os percentuais vêm em pontos percentuais: 2.99 significa 2,99%.

Como ler percentages da taxa transacional

Para uma venda em n parcelas, use o índice n - 1.

Como chegar à taxa efetiva

As taxas vêm como estão configuradas. A rota não escolhe a linha da bandeira nem a parcela. Para a taxa transacional (tx_spread):
  1. Filtre as linhas com feeType tx_spread, paymentMethod e currencyCode iguais aos da venda.
  2. No cartão, use a linha com brand igual à bandeira do cartão. Se ela não existir, use a linha brand: null.
  3. O percentual é definition.percentages[parcelas - 1]. A taxa fixa é definition.fixed, cobrada por transação.
Para a taxa de antecipação (anticipation):
  • só definition.percentages[0] é usado;
  • é uma taxa mensal, multiplicada pelo número de meses até o vencimento da parcela, com mínimo de 1 mês;
  • só incide quando o recebível é antecipado. Sem antecipação, ela não é cobrada.
O desenho abaixo resume como escolher, na lista fees, a linha e o percentual que valem para uma venda. O código abaixo, também usado em Cálculo de split, faz a seleção da taxa transacional:
TypeScript

Exemplo de seleção

Considere uma subconta com estas linhas (valores ilustrativos):
Em uma venda Visa de R$ 600,00 em 6x, a taxa transacional soma 600 × 5,49% + 0,50 = R$ 33,44, e o valor líquido é R$ 566,56. Se o lojista antecipar, cada parcela paga ainda a antecipação: com a taxa mensal de 1,99% do exemplo, uma parcela que vence em 3 meses paga 1,99% × 3 = 5,97% sobre o valor dela.

Passo a passo

Mostrar as taxas ao lojista

Com a lista fees, a sua plataforma monta uma tabela por método e parcela. O exemplo abaixo continua o bloco da função obterTaxasFinvia, mais acima nesta página:
Node.js

Usar no cálculo do split

A taxa transacional alimenta a fórmula do split quando a sua comissão é sobre o valor bruto. Veja o exemplo completo em Cálculo de split.
Por padrão, o split incide sobre o valor líquido da taxa transacional. A taxa de antecipação só reduz a base do split quando o originador antecipa o recebível. Veja Split de pagamentos.

Erros comuns

Perguntas frequentes

Ela recebe uma cópia das taxas da master no momento da criação. Depois disso, as taxas são independentes: mudar as taxas da master não altera as das subcontas já criadas.
A subconta não tem taxas configuradas. Nesse caso, as cobranças dela são recusadas com 422 Fees not configured. Acione o suporte da Finvia; não use as taxas da master no lugar.
Não. Com a chave da master, informar o id da própria master responde 404. A rota é para subcontas.
Não. Autenticada como subconta, a rota devolve os próprios dados mesmo sem essa configuração. A exigência vale para a conta master.
Em pontos percentuais: 2.99 é 2,99%. Para usar na fórmula do split, divida por 100.
Não. fees-info traz só as taxas transacionais e de antecipação.

Como testar

O roteiro de homologação não tem cenário próprio para esta rota. Se a sua integração usa as taxas para calcular o split, os cenários SPL-05 (conferência do percentual e da base de cada recebedor) e SPL-06 (Pix e cartão parcelado) do roteiro de homologação comprovam que a leitura das taxas está correta.

Veja também

Cálculo de split

Use as taxas para calcular a comissão sobre o bruto.

Taxas e dados (referência)

Referência completa da rota.

Split de pagamentos

Regras e exemplos de divisão de vendas.

Connect: visão geral

Conta master, subcontas e mapa das rotas.