> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Taxas da subconta

> Consulte as taxas transacionais e de antecipação de uma subconta, junto com a razão social e o CNPJ, para mostrar ao lojista e para calcular o split.

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

| Situação | Como a rota ajuda |
| - | - |
| Tela "minhas taxas" para o vendedor na sua plataforma | Lista as taxas por método, bandeira e parcela |
| Simulador de recebimento ("quanto vou receber em 6x?") | Fornece os percentuais por parcela e a taxa fixa |
| Comissão da plataforma sobre o valor bruto | Fornece `f` e `c` para o [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) |
| Conferência cadastral | Traz razão social e CNPJ da subconta |

> [!NOTE]
>
> **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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> `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:

| Conta autenticada | Comportamento |
| - | - |
| **Conta master** | Usa o `id` do caminho e devolve a subconta vinculada a ela. Um `id` de subconta de outra master, inexistente ou o próprio `id` da master responde `404`. Exige o Connect habilitado na master, senão `403` |
| **Subconta** | Devolve **sempre os próprios dados**. O `id` do caminho é ignorado. Não depende do Connect estar habilitado |

> [!TIP]
>
> **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

| Campo | Tipo | Descrição |
| - | - | - |
| `merchant.id` | string | Id da subconta (KSUID) |
| `merchant.legalName` | string | Razão social |
| `merchant.companyTaxId` | string | CNPJ, somente dígitos, 14 caracteres |
| `fees` | array | Linhas de taxa da subconta, em lista plana, ordenada por tipo, método, moeda e bandeira. Vazia quando a subconta não tem taxas configuradas |
| `fees[].feeType` | string | `tx_spread` (taxa transacional) ou `anticipation` (taxa de antecipação) |
| `fees[].paymentMethod` | string ou `null` | Método de pagamento (ex.: `credit_card`, `pix`). `null` para taxas sem método associado |
| `fees[].currencyCode` | string ou `null` | Moeda no padrão ISO 4217 (ex.: `BRL`). `null` quando não se aplica |
| `fees[].brand` | string ou `null` | Bandeira do cartão (`visa`, `mastercard`, `elo`). `null` é a taxa padrão, que vale para qualquer bandeira sem taxa própria |
| `fees[].definition.fixed` | number | Taxa fixa por transação, na moeda da linha |
| `fees[].definition.percentages` | number\[] | Na taxa transacional, percentual por parcela: índice `0` = à vista (1x) até índice `11` = 12x. Na antecipação, só o índice `0` é usado |

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

### Como ler `percentages` da taxa transacional

| Índice | Parcelas | Exemplo (`[2.99, 3.49, 3.99, 4.49, 4.99, 5.49, ...]`) |
| - | - | - |
| `0` | 1x (à vista) | 2,99% |
| `1` | 2x | 3,49% |
| `2` | 3x | 3,99% |
| `5` | 6x | 5,49% |
| `11` | 12x | último valor da lista |

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.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    INI(["Lista fees da subconta<br/>GET .../fees-info"]):::finvia
    Q1{"Qual taxa<br/>você procura?"}:::decisao
    TX["Filtre as linhas tx_spread<br/>pelo método e pela moeda<br/>da venda"]:::neutro
    Q2{"Encontrou<br/>alguma linha?"}:::decisao
    ERR["Cobrança recusada<br/>422 Fees not configured<br/>acione o suporte"]:::erro
    Q3{"Há linha com a<br/>bandeira do cartão?"}:::decisao
    BR["Use a linha<br/>da bandeira"]:::neutro
    NUL["Use a linha<br/>brand: null"]:::neutro
    RES(["Taxa da venda<br/>percentages[parcelas − 1]<br/>+ definition.fixed"]):::ok
    ANT["Linha anticipation<br/>percentages[0] por mês"]:::neutro
    QA{"O recebível<br/>foi antecipado?"}:::decisao
    ANTSIM(["Taxa mensal × meses<br/>até o vencimento<br/>mínimo de 1 mês"]):::alerta
    ANTNAO(["Não é cobrada"]):::neutro
    INI --> Q1
    Q1 -->|"transacional"| TX
    Q1 -->|"antecipação"| ANT
    TX --> Q2
    Q2 -->|"não"| ERR
    Q2 -->|"sim"| Q3
    Q3 -->|"sim"| BR
    Q3 -->|"não, ou é Pix"| NUL
    BR --> RES
    NUL --> RES
    ANT --> QA
    QA -->|"sim"| ANTSIM
    QA -->|"não"| ANTNAO
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

O código abaixo, também usado em [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md), faz a seleção da taxa transacional:

```ts TypeScript theme={null}
interface FeeItem {
  feeType: "tx_spread" | "anticipation";
  paymentMethod: string | null;
  currencyCode: string | null;
  brand: string | null;
  definition: { fixed: number; percentages: number[] };
}

interface Filtro {
  paymentMethod: string; // ex.: "credit_card"
  currencyCode: string;  // ex.: "BRL"
  brand: string | null;  // ex.: "visa"; null no Pix
  parcelas: number;      // ex.: 2; 1 no Pix
}

function obterTaxasFinvia(fees: FeeItem[], filtro: Filtro) {
  const candidatas = fees.filter(
    (i) =>
      i.feeType === "tx_spread" &&
      i.paymentMethod === filtro.paymentMethod &&
      i.currencyCode === filtro.currencyCode,
  );
  // a linha da bandeira tem prioridade; cai em brand: null quando não houver
  const linha =
    candidatas.find((i) => i.brand === filtro.brand) ??
    candidatas.find((i) => i.brand === null);

  if (!linha) {
    // sem taxa para a combinação: a cobrança seria recusada com 422 Fees not configured
    throw new Error("Taxa não configurada para este método e moeda. Fale com o suporte da Finvia.");
  }

  const percentual = linha.definition.percentages[filtro.parcelas - 1];
  if (percentual === undefined) {
    throw new Error(`Sem taxa para ${filtro.parcelas} parcelas.`);
  }

  return {
    taxaPercentualFinvia: percentual / 100, // f
    taxaFixaFinvia: linha.definition.fixed, // c
  };
}

// Taxa de antecipação de uma parcela, em pontos percentuais (só quando antecipada)
function taxaAntecipacao(fees: FeeItem[], paymentMethod: string, currencyCode: string, mesesAteVencimento: number) {
  const linha = fees.find(
    (i) => i.feeType === "anticipation" && i.paymentMethod === paymentMethod && i.currencyCode === currencyCode,
  );
  if (!linha) return 0;
  return linha.definition.percentages[0] * Math.max(1, mesesAteVencimento);
}
```

### Exemplo de seleção

Considere uma subconta com estas linhas (valores ilustrativos):

```json theme={null}
{
  "merchant": {
    "id": "2v2TGGb4NHTQWCiMmnelz2WVOZP",
    "legalName": "LOJA EXEMPLO LTDA",
    "companyTaxId": "11222333000181"
  },
  "fees": [
    {
      "feeType": "anticipation",
      "paymentMethod": "credit_card",
      "currencyCode": "BRL",
      "brand": null,
      "definition": { "fixed": 0, "percentages": [1.99] }
    },
    {
      "feeType": "tx_spread",
      "paymentMethod": "credit_card",
      "currencyCode": "BRL",
      "brand": null,
      "definition": { "fixed": 0.5, "percentages": [3.19, 3.69, 4.19, 4.69, 5.19, 5.69, 6.19, 6.69, 7.19, 7.69, 8.19, 8.69] }
    },
    {
      "feeType": "tx_spread",
      "paymentMethod": "credit_card",
      "currencyCode": "BRL",
      "brand": "visa",
      "definition": { "fixed": 0.5, "percentages": [2.99, 3.49, 3.99, 4.49, 4.99, 5.49, 5.99, 6.49, 6.99, 7.49, 7.99, 8.49] }
    },
    {
      "feeType": "tx_spread",
      "paymentMethod": "pix",
      "currencyCode": "BRL",
      "brand": null,
      "definition": { "fixed": 0, "percentages": [1.5] }
    }
  ]
}
```

| Venda | Linha `tx_spread` usada | Taxa transacional | Taxa fixa |
| - | - | - | - |
| Visa em 6x | `brand: "visa"`, índice 5 | 5,49% | R\$ 0,50 |
| Mastercard em 6x | `brand: null` (não há linha Mastercard), índice 5 | 5,69% | R\$ 0,50 |
| Visa à vista | `brand: "visa"`, índice 0 | 2,99% | R\$ 0,50 |
| Pix | `pix`, valor único | 1,5% | R\$ 0,00 |

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

```bash cURL (conta master) theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info" \
  -u "$FINVIA_API_KEY:"
```

```bash cURL (subconta) theme={null}
# Com a chave da subconta, o id do caminho é ignorado
curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info" \
  -u "$SUBCONTA_SECRET_KEY:"
```

```javascript Node.js theme={null}
async function consultarFeesInfo(subcontaId) {
  const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

  const response = await fetch(
    `https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/${subcontaId}/fees-info`,
    { headers: { Authorization: `Basic ${credentials}` } },
  );

  if (!response.ok) {
    const erro = await response.json();
    throw new Error(`${erro.statusCode}: ${erro.message}`);
  }

  return response.json(); // { merchant, fees }
}
```

### 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:

```javascript Node.js theme={null}
function tabelaDeTaxasCartao(fees, bandeira) {
  const linhas = [];
  for (let parcelas = 1; parcelas <= 12; parcelas++) {
    const { taxaPercentualFinvia, taxaFixaFinvia } = obterTaxasFinvia(fees, {
      paymentMethod: 'credit_card',
      currencyCode: 'BRL',
      brand: bandeira,
      parcelas,
    });
    linhas.push({
      parcelas: `${parcelas}x`,
      percentual: `${(taxaPercentualFinvia * 100).toFixed(2)}%`,
      fixa: `R$ ${taxaFixaFinvia.toFixed(2)}`,
    });
  }
  return linhas;
}
```

### 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](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md).

> [!NOTE]
>
> 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](https://docs.fastpaybrasil.com/guias/fast-connect/split.md).

## Erros comuns

| HTTP | Mensagem | Causa | Como resolver |
| - | - | - | - |
| `401` | `Não autorizado` | Credencial inválida ou ausente | Confira a chave e o formato do Basic ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)) |
| `403` | `Fast Connect não habilitado para esta conta` | Conta não é merchant ou a master não tem o Connect habilitado | Peça à Finvia a liberação do módulo |
| `404` | `Subconta não encontrada` | Com a chave da master: `id` de subconta não vinculada, inexistente ou o `id` da própria master | Use o `id` de uma subconta sua. Para ver as taxas da master, esta rota não serve |
| `fees` vazio | | A subconta não tem taxas configuradas; as cobranças dela são recusadas com `422` `Fees not configured` | Acione o suporte da Finvia para configurar |
| Taxas da subconta diferentes das da master | | As taxas são copiadas só na criação; depois, são independentes | Peça à Finvia a replicação, se for o caso |
| Taxa errada em uma bandeira | | Linha `brand: null` usada quando havia linha da bandeira | Priorize a linha da bandeira |

## Perguntas frequentes

> [accordion] A subconta recebe as taxas da master?
>
> 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.

> [accordion] Por que fees veio vazio?
>
> 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.

> [accordion] Consigo consultar as taxas da própria conta master por esta rota?
>
> Não. Com a chave da master, informar o `id` da própria master responde `404`. A rota é para subcontas.

> [accordion] A subconta precisa do Connect habilitado para consultar?
>
> 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.

> [accordion] Os percentuais vêm em fração ou em pontos percentuais?
>
> Em pontos percentuais: `2.99` é 2,99%. Para usar na fórmula do split, divida por 100.

> [accordion] A rota mostra a taxa de saque ou a reserva financeira?
>
> 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](https://docs.fastpaybrasil.com/homologacao/roteiro.md) comprovam que a leitura das taxas está correta.

## Veja também

> [card] [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)
>
> Use as taxas para calcular a comissão sobre o bruto.

> [card] [Taxas e dados (referência)](https://docs.fastpaybrasil.com/referencia/fast-connect/taxas-e-dados.md)
>
> Referência completa da rota.

> [card] [Split de pagamentos](https://docs.fastpaybrasil.com/guias/fast-connect/split.md)
>
> Regras e exemplos de divisão de vendas.

> [card] [Connect: visão geral](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md)
>
> Conta master, subcontas e mapa das rotas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.