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

# Introdução

> O que a API da Finvia faz, para quem esta documentação foi escrita e por onde começar a leitura.

A API da Finvia conecta o sistema da sua empresa à operação de pagamentos. Com ela você gera cobranças Pix e de cartão de crédito, guarda cartões para recompra, cobra assinaturas automaticamente, divide o valor de uma venda entre várias contas, solicita saques por Pix da própria conta e das subcontas e acompanha cada mudança por notificações enviadas ao seu servidor.

Os meios de pagamento são dois: cartão de crédito (inclusive cartão salvo e Apple Pay) e Pix. Tudo acontece por requisições HTTPS com corpo em JSON, autenticadas com a chave secreta da sua conta. O mesmo endereço atende o ambiente de testes (sandbox) e o de produção: o que define o ambiente é a chave usada.

O desenho abaixo mostra quem conversa com quem em uma integração típica, do pagamento do comprador ao aviso que chega ao seu servidor.

```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
    C(["Comprador"]):::comprador
    FE["Seu front-end<br/>site, checkout ou app"]:::lojista
    SV["Seu servidor<br/>guarda a chave secreta sk_"]:::lojista
    API["Finvia API"]:::finvia
    ADQ["Adquirente e bandeiras<br/>cartão e Apple Pay"]:::externo
    PIX["Sistema Pix<br/>banco do comprador"]:::externo
    EV[["Webhooks e postbackUrl<br/>charge.* · subscription.*<br/>payout.*"]]:::evento
    BANK["Conta bancária<br/>da sua empresa"]:::externo
    RX["Seu receptor de webhooks<br/>HTTPS, responde 2xx"]:::lojista
    C -->|"1. escolhe e paga"| FE
    FE -->|"2. envia o pedido"| SV
    FE -.->|"Apple Pay e 3D Secure<br/>com a chave pública pk_"| API
    SV -->|"3. HTTPS + JSON<br/>Basic com a sk_"| API
    API -.->|"4. resposta<br/>com o status"| SV
    API -->|"cartão"| ADQ
    API -->|"Pix"| PIX
    API -->|"5. avisa cada mudança"| EV
    API -->|"saque por Pix<br/>para a chave CNPJ"| BANK
    EV -->|"6. POST no seu endereço"| RX
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    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
```

A chave secreta (`sk_`) fica só no seu servidor. O front-end usa a chave pública (`pk_`) apenas no Apple Pay e no 3D Secure, e o saque sai sempre por Pix para a chave CNPJ da conta.

## Antes de começar

Para integrar, sua empresa precisa de:

* Conta ativa na Finvia e acesso ao [painel](https://app.finvia.com.br).
* A chave de produção, criada automaticamente para o proprietário da conta, ou uma chave gerada por um usuário com perfil **Owner** ou **Manager** (veja [Permissões da chave](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#permissões-da-chave)).
* Um servidor que receba requisições HTTPS da internet, para os webhooks. No desenvolvimento, uma ferramenta como o ngrok expõe sua máquina local.
* Para o marketplace: o módulo Connect habilitado pela Finvia na sua conta.

## O que dá para fazer com a API

| Necessidade do negócio | Recurso da API | Onde aprender |
| - | - | - |
| Receber por Pix, com QR Code ou código copia e cola | Cobrança Pix, com validade mínima de 15 minutos | [Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) |
| Vender no cartão, à vista ou parcelado em até 12x | Cobrança com cartão de crédito | [Cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md) |
| Permitir recompra sem digitar o cartão de novo | Cartão salvo no cofre da Finvia (o comprador informa só o CVV) | [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) e [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md) |
| Aceitar a carteira digital da Apple no site | Apple Pay, com o token do dispositivo repassado ao processador | [Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md) |
| Autenticar o comprador junto ao banco emissor do cartão | 3D Secure em três formatos: gerenciado pela Finvia, pelo SDK ou pela API | [3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md) |
| Cobrar o mesmo cliente todo mês, semana ou quinzena | Planos e assinaturas, com período de teste e retentativa automática | [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) |
| Operar como marketplace ou plataforma com vários vendedores | Connect: conta master, subcontas e divisão de valores (split) | [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md) e [Split](https://docs.fastpaybrasil.com/guias/fast-connect/split.md) |
| Transferir o saldo para a conta bancária da empresa | Saque da própria conta, via Pix para a chave CNPJ da conta | [Saldos e meios de pagamento](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md) e [Criar saque](https://docs.fastpaybrasil.com/referencia/saques/criar.md) |
| Transferir o saldo de um vendedor para a conta dele | Saque de subconta, via Pix para a chave CNPJ da subconta | [Saques](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md) |
| Saber quando algo mudou sem ficar consultando a API | Webhooks de cobrança, assinatura, saque e conta | [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md) |
| Consultar quanto há disponível, pendente e reservado | Saldos por moeda (carteiras) | [Saldos e meios de pagamento](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md) |
| Devolver o dinheiro ao cliente ou acompanhar uma disputa | Estorno total; bloqueio da cobrança em chargeback (cartão) ou MED, o Mecanismo Especial de Devolução do Pix | [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md) e [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md) |

> [!NOTE]
>
> **Para o negócio:** a API é a mesma para todos os modelos de venda. Uma loja virtual usa Pix, cartão e webhooks. Um SaaS soma planos e assinaturas. Um marketplace acrescenta o Connect, que cria uma subconta para cada vendedor e separa a parte de cada um em toda venda. Os [casos de uso](https://docs.fastpaybrasil.com/casos-de-uso/visao-geral.md) mostram essas combinações com exemplos completos.

## Para quem é esta documentação

Cada página foi escrita para ser lida por duas pessoas ao mesmo tempo.

| Leitor | O que encontra aqui |
| - | - |
| **Desenvolvedor** | Qual rota chamar, o que enviar, o que volta, quais erros tratar e como testar no sandbox. Exemplos em cURL e Node.js prontos para adaptar. |
| **Analista de negócios** | O que cada recurso resolve, quando usar, quais regras limitam o produto (prazos, valores mínimos, o que não é possível fazer) e o que pedir ao time técnico. |

Ao longo das páginas, dois quadros ajudam a separar os assuntos:

> [!NOTE]
>
> **Para o negócio:** decisões, regras comerciais e impactos para a operação.

> [!TIP]
>
> **Para o desenvolvedor:** detalhes de implementação, armadilhas de código e formas de depurar.

## Como a documentação está organizada

O portal tem cinco abas. Cada uma responde a uma pergunta diferente.

| Aba | Pergunta que responde | O que tem dentro |
| - | - | - |
| **Documentação** | Como a API funciona? | Esta introdução, [conceitos](https://docs.fastpaybrasil.com/conceitos.md), [mapa da API](https://docs.fastpaybrasil.com/mapa-da-api.md), [glossário](https://docs.fastpaybrasil.com/glossario.md), primeiros passos e anexos de consulta (status, eventos e erros) |
| **Casos de uso** | Como o meu tipo de negócio usa a API? | Cenários completos por segmento, com arquitetura, passo a passo e checklist |
| **Guias** | Como implemento um recurso específico? | Pix, cartão, 3D Secure, assinaturas, Connect, webhooks, estorno e saldos, com regras de negócio e exemplos |
| **Referência da API** | Quais são os campos exatos de cada rota? | As 54 rotas, com parâmetros, respostas, códigos HTTP e exemplos |
| **Homologação** | O que preciso comprovar antes de ir para produção? | Roteiro de cenários de teste e checklist de virada |

## Caminho recomendado de leitura

> [tab] Desenvolvedor
>
> **1. Configure as credenciais**
>
> Gere a chave de teste e faça a primeira chamada autenticada em [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md).
>
> **2. Crie a primeira cobrança**
>
> Siga o tutorial [Sua primeira cobrança](https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca.md): Pix e cartão no sandbox, com recebimento de webhook.
>
> **3. Entenda os contratos gerais**
>
> Leia [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md) e [Erros e como tratar](https://docs.fastpaybrasil.com/primeiros-passos/erros.md). Eles valem para todas as rotas.
>
> **4. Implemente os recursos do seu modelo**
>
> Abra o [caso de uso](https://docs.fastpaybrasil.com/casos-de-uso/visao-geral.md) mais próximo do seu negócio e siga os guias que ele indica.
>
> **5. Consulte a referência e os anexos**
>
> Use a [Referência da API](https://docs.fastpaybrasil.com/referencia/introducao.md) para os campos exatos e os anexos de [status](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md), [eventos](https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md) e [códigos de erro](https://docs.fastpaybrasil.com/anexos/codigos-de-erro.md) durante o desenvolvimento.
>
> **6. Homologue**
>
> Execute os cenários do [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md), envie as evidências ao suporte da Finvia e confira o [checklist de go-live](https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md).

> [tab] Analista de negócios
>
> **1. Aprenda o vocabulário**
>
> Leia [Conceitos essenciais](https://docs.fastpaybrasil.com/conceitos.md) e deixe o [Glossário](https://docs.fastpaybrasil.com/glossario.md) aberto para consulta.
>
> **2. Encontre o seu cenário**
>
> Escolha o [caso de uso](https://docs.fastpaybrasil.com/casos-de-uso/visao-geral.md) mais parecido com a sua operação. Ele mostra quais recursos entram e quais regras precisam ser decididas.
>
> **3. Revise as regras que afetam o produto**
>
> Nos guias, leia as seções "Quando usar" e "Regras de negócio". Pontos que costumam virar decisão: validade do Pix, parcelamento, período de arrependimento das assinaturas, base de cálculo do split e taxa de saque.
>
> **4. Entenda o pós-venda**
>
> Veja [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md) e [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md) para definir quando liberar um pedido e como tratar disputas.
>
> **5. Acompanhe a homologação**
>
> Use o [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md) para saber o que o time técnico deve comprovar antes da produção. A homologação é recomendada e acompanhada pela equipe Finvia, por meio do suporte.

## Primeiros passos

> [card] [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)
>
> Gere suas chaves e faça a primeira chamada autenticada.

> [card] [Sua primeira cobrança](https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca.md)
>
> Pix e cartão no sandbox, da criação ao webhook.

> [card] [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md)
>
> Como listar dados e evitar cobranças duplicadas.

> [card] [Erros e como tratar](https://docs.fastpaybrasil.com/primeiros-passos/erros.md)
>
> Formatos de erro, códigos HTTP e boas práticas de retentativa.

## Casos de uso

> [card] [E-commerce](https://docs.fastpaybrasil.com/casos-de-uso/e-commerce.md)
>
> Loja virtual com Pix, cartão parcelado e produtos físicos.

> [card] [SaaS e assinaturas](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md)
>
> Planos recorrentes, período de teste e cancelamento.

> [card] [Marketplace e PSP](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md)
>
> Subcontas por vendedor, split e saques com o Connect.

> [card] [Infoprodutos](https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md)
>
> Cursos e produtos digitais, com divisão de valores entre parceiros.

> [card] [ERP e software de gestão](https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md)
>
> Pagamentos embutidos no sistema que seus clientes já usam.

> [card] [Cobrança por mensagem](https://docs.fastpaybrasil.com/casos-de-uso/cobranca-por-link.md)
>
> Cobranças enviadas por mensagem, e-mail ou WhatsApp.

> [card] [White label e agências](https://docs.fastpaybrasil.com/casos-de-uso/white-label-agencias.md)
>
> Agências e plataformas que integram pagamentos para vários clientes.

> [card] [Educação e mensalidades](https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md)
>
> Mensalidades escolares e cursos com cobrança recorrente.

## Convenções que valem para toda a API

| Tema | Regra |
| - | - |
| Endereço | `https://api-global.fastpaybrasil.com`, igual para sandbox e produção. O painel fica em `https://app.finvia.com.br` |
| Autenticação | HTTP Basic com a chave secreta, inclusive em saldo e saques. Apple Pay (validação de sessão) e 3D Secure usam a chave pública, e o envio de documentos com token usa o token de upload (veja o [mapa da API](https://docs.fastpaybrasil.com/mapa-da-api.md)) |
| Valores | Em **reais**, com decimais: `10` significa R\$ 10,00 e `99.9` significa R\$ 99,90 |
| Datas | Texto no padrão ISO 8601, como `2024-01-15T10:30:00.000Z` |
| Identificadores | Texto, como `2vorkDcXyvzifL63YX09S9VqcnI` |
| Nomes de campo | camelCase nas requisições e respostas da API. Os webhooks de cobrança e assinatura usam snake\_case no primeiro nível de `data` |
| Meios de pagamento | Cartão de crédito (avulso, salvo e Apple Pay) e Pix |
| Notificações | Webhooks cadastrados no painel e `postbackUrl` informada na cobrança |

## Veja também

> [card] [Conceitos essenciais](https://docs.fastpaybrasil.com/conceitos.md)
>
> Merchant, cobrança, webhook, split e outros termos explicados.

> [card] [Mapa da API](https://docs.fastpaybrasil.com/mapa-da-api.md)
>
> Todas as rotas em uma página, agrupadas por assunto.

> [card] [Glossário](https://docs.fastpaybrasil.com/glossario.md)
>
> Termos de pagamentos e da API em ordem alfabética.

> [card] [Roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> O que testar antes de ir para produção.


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