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

# Mapa da API

> As 54 rotas da API da Finvia em uma página, agrupadas por assunto, com o que cada uma faz e como se autentica.

Use esta página como índice. Cada tabela reúne as rotas de um assunto, explica em linguagem de negócio o que cada uma faz e mostra a autenticação usada. O link da última coluna leva à página de referência, com todos os campos, respostas e exemplos.

Todas as rotas usam a mesma URL base, para sandbox e produção:

```text theme={null}
https://api-global.fastpaybrasil.com
```

## Como ler a coluna de autenticação

| Valor na tabela | O que enviar no cabeçalho `Authorization` |
| - | - |
| **Basic, chave secreta** | `Basic` + Base64 de `sk_...:` (ou `sk_test_...:` no sandbox). É o padrão da API, inclusive em saldo, saques e endpoints de webhook |
| **Basic, chave pública** | `Basic` + Base64 de `pk_...:` (ou `pk_test_...:`). Usada nas rotas chamadas pelo navegador: validação de sessão do Apple Pay e 3D Secure |
| **Bearer, token de upload** | `Bearer` + token emitido por `POST /v1/submerchants/{merchantId}/document/upload-token`. Só no envio de documentos com token |

A chave age com as permissões do usuário que a gerou. Uma chave de perfil sem permissão recebe `403` com `Acesso negado` (veja [Permissões da chave](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#permissões-da-chave)). Como montar o Basic: [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md).

O desenho abaixo mostra de onde parte cada chamada e qual credencial ela usa.

```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 LR
    SV["Seu servidor"]:::lojista
    BR["Navegador ou app<br/>do comprador"]:::lojista
    PK{{"Basic com a<br/>chave pública pk_"}}:::finvia
    TK{{"Bearer com o<br/>token de upload"}}:::finvia
    SK{{"Basic com a<br/>chave secreta sk_"}}:::finvia
    R1["Apple Pay<br/>validate-merchant"]:::evento
    R2["3D Secure<br/>three-ds/* e resume-3ds"]:::evento
    R3["Envio de documentos<br/>document-uploads"]:::evento
    R4["Demais rotas<br/>cobranças, assinaturas,<br/>Connect, saques e outras"]:::evento
    SV --> SK
    BR --> TK
    BR --> PK
    SK --> R4
    TK --> R3
    PK --> R1
    PK --> R2
    SK -.->|"upload-token emite<br/>o token (300 s)"| TK
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
```

## Visão geral por grupo

| Grupo | Rotas | Para que serve |
| - | - | - |
| Cobranças | 5 | Criar, listar, consultar, estornar e simular eventos de cobranças |
| Apple Pay | 5 | Registrar e verificar domínios e validar a sessão de pagamento no navegador |
| Saldos e meios de pagamento | 2 | Consultar saldo por moeda e meios de pagamento habilitados |
| Saques | 2 | Sacar o saldo da própria conta por Pix e acompanhar os saques |
| Clientes | 5 | Cadastro de quem paga |
| Cartões | 4 | Cofre de cartões para recompra e assinaturas |
| 3D Secure | 5 | Autenticação do comprador junto ao banco emissor |
| Planos de assinatura | 7 | Modelos de cobrança recorrente |
| Assinaturas | 5 | Vínculo de um cliente a um plano |
| Connect | 10 | Subcontas, documentos, chaves, taxas e saques do marketplace |
| Endpoints de webhook | 4 | Cadastrar, listar, alterar e excluir os endereços que recebem os webhooks |
| **Total** | **54** | |

O desenho abaixo organiza os grupos na ordem em que costumam aparecer em uma integração, da preparação da conta ao saque.

```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": {"defaultRenderer": "elk", "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
    subgraph S1["1. Preparar a conta"]
        PM["Meios de pagamento<br/>testa a chave"]:::neutro
        WE["Webhooks<br/>onde chegam os avisos"]:::neutro
        AP["Apple Pay<br/>registra o domínio"]:::neutro
        FC["Connect<br/>subcontas e documentos"]:::neutro
    end
    subgraph S2["2. Cadastrar quem paga"]
        CL["Clientes"]:::comprador
        CA["Cartões<br/>cofre para recompra"]:::comprador
    end
    subgraph S3["3. Cobrar"]
        TD["3D Secure<br/>autentica o comprador"]:::neutro
        CH["Cobranças<br/>Pix e cartão"]:::finvia
        PL["Planos de assinatura"]:::neutro
        SU["Assinaturas<br/>cobram a cada ciclo"]:::neutro
    end
    subgraph S4["4. Depois da venda"]
        RF["Cobranças<br/>consulta e estorno"]:::neutro
        SA["Saldos e saques<br/>Pix para a chave CNPJ"]:::neutro
    end
    CL --> CA
    CL --> CH
    CA --> SU
    CA -.->|"recompra"| CH
    PL --> SU
    TD --> CH
    SU -->|"gera"| CH
    CH --> RF
    CH --> SA
    S1 --> S2
    style S1 fill:#F7F9FC,stroke:#D5DCE6
    style S2 fill:#F7F9FC,stroke:#D5DCE6
    style S3 fill:#F7F9FC,stroke:#D5DCE6
    style S4 fill:#F7F9FC,stroke:#D5DCE6
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

A ordem é uma sugestão. Os grupos que você vai usar dependem do seu modelo de negócio, como mostram os [casos de uso](https://docs.fastpaybrasil.com/casos-de-uso/visao-geral.md).

## Cobranças

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `GET` | `/v1/charges` | Lista as cobranças, da mais recente para a mais antiga, com filtros por `status`, `currency`, período (`createdAtStart` e `createdAtEnd`) e busca (`searchFor`) | Basic, chave secreta | [Listar cobranças](https://docs.fastpaybrasil.com/referencia/cobrancas/listar.md) |
| `POST` | `/v1/charges` | Cria uma cobrança Pix, cartão, cartão salvo ou Apple Pay, com split opcional | Basic, chave secreta | [Criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md) |
| `GET` | `/v1/charges/{id}` | Consulta uma cobrança pelo `id`: status atual, valores, cliente, detalhes do pagamento e `splits` | Basic, chave secreta | [Consultar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar.md) |
| `POST` | `/v1/refunds` | Solicita o estorno total de uma cobrança paga | Basic, chave secreta | [Estornar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/estornar.md) |
| `POST` | `/v1/charges/{id}/resend-webhook` | Gera um evento simulado, com o status escolhido, para uma cobrança de teste. Não altera a cobrança (só sandbox) | Basic, chave secreta | [Simular webhook de teste](https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste.md) |

> [!TIP]
>
> **Para o desenvolvedor:** `GET /v1/charges` não busca por `metadata` nem por identificador do seu pedido, e ignora `orderBy`. Guarde o `id` devolvido na criação junto com o seu pedido. Depois de um timeout, siga o [procedimento de timeout](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#procedimento-depois-de-um-timeout-ao-criar-cobrança).

## Apple Pay

Rotas para preparar o Apple Pay na sua própria integração. Registrar o primeiro domínio ativa na conta o modelo em que a sessão é validada por `validate-merchant`. A cobrança em si usa a rota padrão `POST /v1/charges`.

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `POST` | `/v1/apple-pay/domains` | Registra o hostname onde o botão Apple Pay aparece e devolve o arquivo de verificação. Vale para teste e produção | Basic, chave secreta | [Registrar domínio](https://docs.fastpaybrasil.com/referencia/apple-pay/registrar-dominio.md) |
| `GET` | `/v1/apple-pay/domains` | Lista os domínios da conta e o status de cada um (`pending`, `verified` ou `failed`), sem paginação | Basic, chave secreta | [Listar domínios](https://docs.fastpaybrasil.com/referencia/apple-pay/listar-dominios.md) |
| `GET` | `/v1/apple-pay/domains/{id}` | Consulta um domínio, inclusive o arquivo de verificação | Basic, chave secreta | [Consultar domínio](https://docs.fastpaybrasil.com/referencia/apple-pay/consultar-dominio.md) |
| `POST` | `/v1/apple-pay/domains/{id}/validate` | Confere o arquivo hospedado e marca o domínio como `verified` | Basic, chave secreta | [Validar domínio](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-dominio.md) |
| `POST` | `/v1/apple-pay/validate-merchant` | Valida a sessão Apple Pay no evento `onvalidatemerchant` do navegador | Basic, chave pública | [Validar sessão](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-sessao.md) |

> [!NOTE]
>
> As rotas de domínio exigem que o usuário dono da chave tenha permissão de domínios Apple Pay (perfis Owner, Manager e Desenvolvedor). Em `validate-merchant`, a `pk_test_` também valida a sessão no provedor real, porque a janela de pagamento do Safari só abre com sessão real.

## Saldos e meios de pagamento

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `GET` | `/v1/wallets` | Mostra o saldo da conta por moeda: disponível, pendente e reservado, e se o saque está habilitado. Exige `merchantId` na consulta | Basic, chave secreta | [Listar carteiras](https://docs.fastpaybrasil.com/referencia/carteiras/listar.md) |
| `GET` | `/v1/payment-methods` | Lista os meios de pagamento habilitados para a conta, com filtro opcional por `currency` | Basic, chave secreta | [Listar meios de pagamento](https://docs.fastpaybrasil.com/referencia/meios-de-pagamento/listar.md) |

> [!TIP]
>
> **Para o desenvolvedor:** `GET /v1/payment-methods` é a forma mais simples de testar se a chave e o cabeçalho estão corretos. Resposta `200` significa autenticação válida.

## Saques

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `POST` | `/v1/payout-requests` | Solicita o saque do saldo da própria conta, por Pix para a chave CNPJ da conta. Responde `201` sem corpo | Basic, chave secreta | [Criar saque](https://docs.fastpaybrasil.com/referencia/saques/criar.md) |
| `GET` | `/v1/payout-requests` | Lista os saques, do mais recente para o mais antigo, com filtros por conta, status, moeda e período, e o total de pendentes (`pendingCount`) | Basic, chave secreta | [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) |

> [!WARNING]
>
> Não existe saque no Modo Teste: com a chave de teste, `POST /v1/payout-requests` responde `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`. Uma chave de usuário Desenvolvedor recebe `403` com `Acesso negado` em saldo e saques. O acompanhamento de um saque é feito pela listagem.

## Clientes

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `GET` | `/v1/customers` | Lista clientes, com busca por nome, e-mail, documento ou telefone | Basic, chave secreta | [Listar clientes](https://docs.fastpaybrasil.com/referencia/clientes/listar.md) |
| `POST` | `/v1/customers` | Cadastra um cliente (`name`, `email`, `documentId` e `documentType` obrigatórios) | Basic, chave secreta | [Criar cliente](https://docs.fastpaybrasil.com/referencia/clientes/criar.md) |
| `GET` | `/v1/customers/{id}` | Consulta o cadastro de um cliente | Basic, chave secreta | [Consultar cliente](https://docs.fastpaybrasil.com/referencia/clientes/consultar.md) |
| `PUT` | `/v1/customers/{id}` | Atualiza nome, e-mail ou telefone. O documento não pode ser alterado | Basic, chave secreta | [Atualizar cliente](https://docs.fastpaybrasil.com/referencia/clientes/atualizar.md) |
| `DELETE` | `/v1/customers/{id}` | Remove o cliente (exclusão lógica). Responde `204` sem corpo | Basic, chave secreta | [Excluir cliente](https://docs.fastpaybrasil.com/referencia/clientes/excluir.md) |

## Cartões

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `GET` | `/v1/cards` | Lista os cartões salvos, com filtro opcional por `customerId` | Basic, chave secreta | [Listar cartões](https://docs.fastpaybrasil.com/referencia/cartoes/listar.md) |
| `POST` | `/v1/cards` | Guarda um cartão no cofre e devolve o `id` usado em cobranças e assinaturas | Basic, chave secreta | [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md) |
| `GET` | `/v1/cards/{id}` | Consulta um cartão salvo: final, bandeira, validade e status | Basic, chave secreta | [Consultar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/consultar.md) |
| `DELETE` | `/v1/cards/{id}` | Revoga o cartão no cofre. Ele não pode mais ser usado em cobranças nem assinaturas | Basic, chave secreta | [Excluir cartão](https://docs.fastpaybrasil.com/referencia/cartoes/excluir.md) |

O cartão já nasce `active` no cadastro, sem etapa de ativação.

> [!WARNING]
>
> `POST /v1/cards` registra o cartão de verdade mesmo com a chave de teste (sem cobrar), e o cofre é o mesmo para teste e produção. A cobrança com cartão salvo (`POST /v1/charges` com `cardTokenId`) é simulada no Modo Teste. Veja [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#o-que-é-simulado-no-modo-teste).

## 3D Secure

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `POST` | `/v1/three-ds/authenticate` | Inicia uma autenticação 3DS e pode devolver a URL de coleta de dados do navegador ou a URL do desafio | Basic, chave pública | [Iniciar autenticação](https://docs.fastpaybrasil.com/referencia/3d-secure/iniciar.md) |
| `POST` | `/v1/three-ds/submit` | Envia a autenticação depois da coleta de dados do navegador e informa se haverá desafio | Basic, chave pública | [Enviar autenticação](https://docs.fastpaybrasil.com/referencia/3d-secure/enviar.md) |
| `POST` | `/v1/three-ds/cancel` | Cancela uma autenticação em `requires_submission` ou `requires_challenge` | Basic, chave pública | [Cancelar autenticação](https://docs.fastpaybrasil.com/referencia/3d-secure/cancelar.md) |
| `POST` | `/v1/three-ds/challenge-result` | Obtém o resultado final do desafio, com o criptograma usado na cobrança | Basic, chave pública | [Resultado do desafio](https://docs.fastpaybrasil.com/referencia/3d-secure/resultado-desafio.md) |
| `POST` | `/v1/charges/{id}/resume-3ds` | Retoma uma cobrança em `authentication_required` depois do 3DS gerenciado. No fluxo gerenciado, quem chama é a própria página de autenticação | Basic, chave pública | [Retomar cobrança](https://docs.fastpaybrasil.com/referencia/3d-secure/retomar-cobranca.md) |

## Planos de assinatura

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `GET` | `/v1/subscription-plans` | Lista os planos, com filtro por `merchantId` e `status` | Basic, chave secreta | [Listar planos](https://docs.fastpaybrasil.com/referencia/planos/listar.md) |
| `POST` | `/v1/subscription-plans` | Cria um plano com preço, moeda, periodicidade e período de teste opcional | Basic, chave secreta | [Criar plano](https://docs.fastpaybrasil.com/referencia/planos/criar.md) |
| `GET` | `/v1/subscription-plans/{id}` | Consulta um plano e o número de assinaturas ativas | Basic, chave secreta | [Consultar plano](https://docs.fastpaybrasil.com/referencia/planos/consultar.md) |
| `PUT` | `/v1/subscription-plans/{id}` | Atualiza um plano. A mudança vale só para novas assinaturas | Basic, chave secreta | [Atualizar plano](https://docs.fastpaybrasil.com/referencia/planos/atualizar.md) |
| `POST` | `/v1/subscription-plans/{id}/image` | Envia a imagem do plano (PNG, JPG ou JPEG) | Basic, chave secreta | [Enviar imagem do plano](https://docs.fastpaybrasil.com/referencia/planos/enviar-imagem.md) |
| `PATCH` | `/v1/subscription-plans/{id}/status` | Ativa um plano na hora ou pede a desativação, que sempre devolve um token de confirmação | Basic, chave secreta | [Alterar status do plano](https://docs.fastpaybrasil.com/referencia/planos/alterar-status.md) |
| `PATCH` | `/v1/subscription-plans/{id}/status/confirm` | Confirma a desativação com o token recebido (válido por 5 minutos) | Basic, chave secreta | [Confirmar desativação](https://docs.fastpaybrasil.com/referencia/planos/confirmar-desativacao.md) |

## Assinaturas

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `GET` | `/v1/subscriptions` | Lista assinaturas, com filtro por merchant, cliente, status e busca por nome ou plano | Basic, chave secreta | [Listar assinaturas](https://docs.fastpaybrasil.com/referencia/assinaturas/listar.md) |
| `POST` | `/v1/subscriptions` | Cria a assinatura de um cliente em um plano, com cartão salvo ou cartão novo | Basic, chave secreta | [Criar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md) |
| `GET` | `/v1/subscriptions/{id}` | Consulta a assinatura com o histórico de cobranças | Basic, chave secreta | [Consultar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/consultar.md) |
| `PATCH` | `/v1/subscriptions/{id}` | Atualiza o `metadata` de uma assinatura ativa (único campo alterável) | Basic, chave secreta | [Atualizar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/atualizar.md) |
| `POST` | `/v1/subscriptions/{id}/cancel` | Cancela a assinatura, com estorno automático em até 7 dias da criação | Basic, chave secreta | [Cancelar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/cancelar.md) |

> [!NOTE]
>
> **Para o negócio:** as chaves geradas por usuários Desenvolvedor ou Financeiro recebem `403` em todas as rotas de planos e assinaturas, e a chave de Desenvolvedor também ao criar cobrança. O perfil Visualizador só acessa as consultas. Use uma chave de usuário Owner ou Manager.

## Connect

Rotas do módulo de marketplace. Exigem o Connect habilitado pela Finvia na conta master.

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `GET` | `/v1/submerchants` | Lista as subcontas da conta master, com filtros por status, busca, período de criação e completude do cadastro | Basic, chave secreta | [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md) |
| `POST` | `/v1/submerchants` | Cria uma subconta (vendedor) com dados da empresa, representante legal e conta bancária | Basic, chave secreta | [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md) |
| `GET` | `/v1/submerchants/{id}` | Consulta uma subconta, com status e métricas de volume e split | Basic, chave secreta | [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md) |
| `POST` | `/v1/submerchants/{id}/document` | Envia os documentos da subconta para análise. Documentos de pessoa vão para o representante legal | Basic, chave secreta | [Enviar documentos](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos.md) |
| `POST` | `/v1/submerchants/{merchantId}/document/upload-token` | Emite um token de upload válido por 300 segundos, opcionalmente vinculado a um sócio | Basic, chave secreta | [Criar token de upload](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-token-upload.md) |
| `POST` | `/v1/document-uploads` | Envia documentos usando o token de upload, inclusive direto do navegador, sem expor a chave | Bearer, token de upload | [Enviar documentos com token](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos-com-token.md) |
| `GET` | `/v1/submerchants/{merchantId}/legal-representatives` | Lista os sócios da subconta e, com `include=documents`, os documentos de cada um | Basic, chave secreta | [Listar representantes](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes.md) |
| `GET` | `/v1/submerchants/{id}/api-keys` | Devolve as chaves pública e secreta da subconta ativa | Basic, chave secreta | [Chaves de API da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/chaves-de-api.md) |
| `GET` | `/v1/fast-connect/sub-accounts/{id}/fees-info` | Mostra as taxas efetivas da subconta (transacionais e de antecipação), a razão social e o CNPJ | Basic, chave secreta | [Taxas e dados da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/taxas-e-dados.md) |
| `POST` | `/v1/submerchants/{merchantId}/payout-requests` | Solicita o saque do saldo da subconta, via Pix para a chave CNPJ dela, sempre com aprovação manual | Basic, chave secreta | [Criar saque da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-saque.md) |

Os saques das subcontas são acompanhados pela listagem [`GET /v1/payout-requests`](https://docs.fastpaybrasil.com/referencia/saques/listar), que, para a conta master, traz também os saques das subcontas. Filtre por `merchantId` para ver uma conta só.

## Endpoints de webhook

Rotas para cadastrar pela API os endereços que recebem os webhooks, inclusive os de uma subconta. O corpo usa snake\_case, e o `merchantId` da conta vai na query.

| Método | Rota | O que faz | Autenticação | Referência |
| - | - | - | - | - |
| `POST` | `/v1/webhook-endpoints` | Cadastra um endpoint para a conta indicada em `merchantId`, com `url`, `enabled_events` e, na master com Connect, `include_submerchants`. Responde `201` sem corpo | Basic, chave secreta | [Criar endpoint](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint.md) |
| `GET` | `/v1/webhook-endpoints` | Lista os endpoints da conta indicada em `merchantId`, com busca e paginação | Basic, chave secreta | [Listar endpoints](https://docs.fastpaybrasil.com/referencia/webhooks/listar-endpoints.md) |
| `PUT` | `/v1/webhook-endpoints/{webhookId}` | Altera a URL, os eventos ou a opção de incluir subcontas | Basic, chave secreta | [Atualizar endpoint](https://docs.fastpaybrasil.com/referencia/webhooks/atualizar-endpoint.md) |
| `DELETE` | `/v1/webhook-endpoints/{webhookId}` | Exclui um endpoint | Basic, chave secreta | [Excluir endpoint](https://docs.fastpaybrasil.com/referencia/webhooks/excluir-endpoint.md) |

> [!NOTE]
>
> O endpoint cadastrado pelo painel (**Configurações > Webhooks**) recebe todos os eventos. O filtro por evento (`enabled_events`) só existe pela API; lista vazia significa todos.

## Veja também

> [card] [Introdução à referência](https://docs.fastpaybrasil.com/referencia/introducao.md)
>
> Convenções da referência da API.

> [card] [Conceitos essenciais](https://docs.fastpaybrasil.com/conceitos.md)
>
> O que é cada objeto que aparece nas rotas.

> [card] [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md)
>
> Como funcionam as rotas de listagem.

> [card] [Catálogo de códigos de erro](https://docs.fastpaybrasil.com/anexos/codigos-de-erro.md)
>
> As mensagens de erro de cada rota.


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