> ## 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 e dados da subconta

> Devolve as taxas transacionais e de antecipação, a razão social e o CNPJ de uma subconta do Connect.

Esta rota mostra as taxas configuradas para uma subconta (transacionais e de antecipação) junto com a razão social e o CNPJ dela. São as taxas efetivas: na cobrança, a API usa só as taxas da própria conta que cobra, sem consultar a conta master. Serve para conferir o que cada vendedor paga, montar simuladores de taxa no seu sistema e conciliar valores líquidos.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Mostrar ao vendedor as taxas que ele paga | Chame com a chave da conta master e o `id` da subconta |
| A própria subconta consulta as taxas dela | Chame com a credencial da subconta; o `id` é ignorado |
| Calcular o percentual de split considerando a taxa da Finvia | Use `fees` como base do cálculo ([Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)) |
| Conferir razão social e CNPJ de uma subconta | Use o objeto `merchant` |

## Antes de chamar

* Para consultar como **conta master**, o módulo Connect precisa estar habilitado pela Finvia na sua conta (sem isso, `403`), e a subconta precisa estar ligada a ela.
* Tenha o `id` da subconta, devolvido em [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md) ou em [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md).

## Autenticação

Use a chave secreta (`sk_`) em Basic, como no resto da API. Veja [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md).

## Quem está autenticado muda a resposta

O resultado depende do `id` informado e também de **qual conta** faz a chamada.

| Conta autenticada | Comportamento |
| - | - |
| **Conta master** | Usa o `id` informado e devolve a subconta ligada a ela. `id` de subconta de outra conta master, `id` inexistente ou o `id` da própria conta master devolvem `404`. Exige o Connect habilitado na conta master; sem isso, `403` |
| **Subconta** | Devolve **sempre os próprios dados**. O `id` é ignorado e o Connect não precisa estar habilitado |

## Parâmetros de caminho

**id** `string` *required*

Id (KSUID) da subconta. Obrigatório quando a chamada é feita pela conta master; ignorado quando é feita pela subconta. Ex.: `2v2TGGb4NHTQWCiMmnelz2WVOZP`.

## Respostas

**merchant** `object`

Dados cadastrais da subconta.

**propriedades**

**id** `string`

Id (KSUID) da subconta. Ex.: `2v2TGGb4NHTQWCiMmnelz2WVOZP`.

**legalName** `string`

Razão social. Ex.: `LOJA EXEMPLO LTDA`.

**companyTaxId** `string`

CNPJ, só dígitos, com 14 caracteres. Ex.: `11222333000181`.

**fees** `object[]`

Taxas da subconta, em lista plana, ordenada por tipo, método, moeda e bandeira. Array vazio significa subconta sem taxas configuradas: as cobranças dela são recusadas até a configuração.

**propriedades**

**feeType** `string`

Tipo da taxa: `tx_spread` (transacional) ou `anticipation` (antecipação).

**paymentMethod** `string | null`

Método de pagamento (ex.: `credit_card`, `pix`). `null` para taxas sem método associado.

**currencyCode** `string | null`

Código da moeda no padrão ISO 4217 (ex.: `BRL`). `null` quando não se aplica.

**brand** `string | null`

Bandeira do cartão (`visa`, `mastercard`, `elo`). `null` representa a taxa padrão, que vale para qualquer bandeira sem regra própria.

**definition** `object`

Composição da taxa.

**propriedades**

**fixed** `number`

Taxa fixa por transação, na moeda do item. Ex.: `0.5` (R\$ 0,50 em `BRL`).

**percentages** `number[]`

Taxa percentual por parcela: índice `0` = à vista (1x) até índice `11` = 12x. Um único valor para taxas sem parcelamento. Ex.: `[2.99, 3.49, 3.99, 4.49, 4.99, 5.49, 5.99, 6.49, 6.99, 7.49, 7.99, 8.49]`.

> [!NOTE]
>
> `fees` não traz a reserva financeira nem a taxa de saque da subconta.

### De onde vêm as taxas

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. Se a subconta chegar à pré-aprovação 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.

### Como chegar à taxa efetiva

As taxas vêm **como estão cadastradas**. A rota não escolhe a linha da bandeira nem a parcela por você. Para a taxa transacional (`tx_spread`), siga os passos abaixo.

**1. Filtre pelo tipo, método e moeda**

Ex.: `feeType` `tx_spread`, `paymentMethod` `credit_card`, `currencyCode` `BRL`.

**2. Procure a bandeira do cartão**

Se existir uma linha com a `brand` da venda (ex.: `visa`), use essa linha.

**3. Caia para a taxa padrão**

Se não houver linha da bandeira, use a linha com `brand` `null`.

**4. Escolha o percentual da parcela**

O percentual é `definition.percentages[parcelas - 1]`. No exemplo, 3x usa o índice `2`: 3,99%. A taxa `definition.fixed` é cobrada por transação.

Para a **antecipação** (`anticipation`), só `percentages[0]` é usado. É uma taxa **mensal**, multiplicada pelo número de meses até o vencimento da parcela (mínimo de 1 mês), e só incide quando o recebível é antecipado. Exemplo com `percentages[0]` igual a `1.99`: uma parcela que vence em 3 meses, se antecipada, paga 1,99% × 3 = 5,97% sobre o valor dela.

> [!WARNING]
>
> `fees` vazio, ou sem linha para o método e a moeda da cobrança, significa que a subconta **não tem taxa configurada** para essa combinação. As cobranças dessa combinação são recusadas com `422` `Fees not configured`. Não interprete a lista vazia como taxa zero e não use as taxas da master no lugar: fale com o suporte da Finvia para configurar.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Taxas e dados cadastrais da subconta | `merchant`, `fees` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Não autorizado"}` |
| `403` | Conta que não é merchant, ou Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect não habilitado para esta conta"}` |
| `404` | Subconta não encontrada (não ligada, inexistente ou `id` da própria conta master) | `{"statusCode": 404, "message": "Subconta não encontrada"}` |

> [!NOTE]
>
> **Para o negócio:** a Finvia aplica o percentual de split sobre o **valor líquido**, depois das taxas dela. Se a sua plataforma cobra uma comissão sobre o valor bruto da venda, use as taxas desta rota para chegar ao percentual certo. O passo a passo está em [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `403` "Connect não habilitado para esta conta" | Módulo Connect não habilitado na conta master | Peça a habilitação à Finvia |
| `404` "Subconta não encontrada" | `id` de subconta de outra conta master, inexistente ou o `id` da própria conta master | Use o `id` de uma subconta ligada à sua conta |
| Resposta traz dados de uma subconta diferente do `id` enviado | Chamada feita com a credencial de uma subconta, que sempre devolve os próprios dados | Use a chave da conta master para consultar outras subcontas |
| `fees` vazio | Subconta sem taxas configuradas. As cobranças dela são recusadas com `422` `Fees not configured` | Fale com o suporte da Finvia para configurar as taxas |
| Mudei as taxas da master e a subconta não mudou | As taxas são copiadas só na criação da subconta | Peça à Finvia a replicação para as subcontas |
| Taxa de uma bandeira não aparece | Só existe a taxa padrão (`brand: null`) | Use a linha com `brand` `null` |

```http REST (JSON) theme={null}
GET /v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

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

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const id = '2v2TGGb4NHTQWCiMmnelz2WVOZP';

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

const { merchant, fees } = await response.json();

// Taxa efetiva de cartão Visa em 3x: linha da bandeira ou, se não houver, a padrão
function cardFee(fees, brand, installments) {
  const card = fees.filter(
    (f) => f.feeType === 'tx_spread' && f.paymentMethod === 'credit_card' && f.currencyCode === 'BRL',
  );
  const row = card.find((f) => f.brand === brand) ?? card.find((f) => f.brand === null);
  if (!row) return null; // sem taxa: a cobrança seria recusada com 422 Fees not configured
  return {
    fixed: row.definition.fixed,
    percentage: row.definition.percentages[installments - 1],
  };
}

console.log(cardFee(fees, 'visa', 3)); // { fixed: 0.5, percentage: 3.99 }
```

```python Python theme={null}
import os

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2v2TGGb4NHTQWCiMmnelz2WVOZP/fees-info")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 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": "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]
      }
    }
  ]
}
```

```json 401 theme={null}
{ "statusCode": 401, "message": "Não autorizado" }
```

```json 403 theme={null}
{ "statusCode": 403, "message": "Fast Connect não habilitado para esta conta" }
```

```json 404 theme={null}
{ "statusCode": 404, "message": "Subconta não encontrada" }
```

## Veja também

> [card] [Taxas no Connect](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md)
>
> Como as taxas das subcontas funcionam.

> [card] [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)
>
> Percentual de split considerando as taxas.

> [card] [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md)
>
> Dados e status da subconta.

> [card] [Visão geral do Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md)
>
> Conta master e subcontas.


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