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

# Integrar com IA

> Prompts prontos e atalhos para usar Claude Code, Codex, Gemini, Cursor, ChatGPT e outros assistentes na integração com a API da Finvia.

Assistentes de programação como Claude Code, Codex, Gemini CLI, Cursor e GitHub Copilot fazem boa parte de uma integração quando recebem o contexto certo. Esta página reúne o que eles precisam: prompts prontos por tipo de integração e atalhos para entregar a documentação inteira ao assistente.

> [!NOTE]
>
> O assistente escreve o código, mas a responsabilidade pela integração continua sendo do seu time. Revise o que ele produzir, rode os testes com a chave de teste e siga o [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md) antes de ir para produção.

## Prompts prontos

Clique em **Copy prompt** e cole no assistente que você usa, dentro do projeto que vai receber a integração. No Cursor, o botão **Open in Cursor** abre o prompt direto no editor. Cada prompt aponta para as páginas certas da documentação e já traz as regras que mais causam erro: autenticação, valores em reais, ausência de idempotência na criação de cobranças e tratamento de webhooks.

### Primeira cobrança Pix

Cobrança Pix com QR Code, confirmação por webhook e tratamento de erros.

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)
* [https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca.md](https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca.md)
* [https://docs.fastpaybrasil.com/guias/cobrancas/pix.md](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
* [https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)
* [https://docs.fastpaybrasil.com/primeiros-passos/erros.md](https://docs.fastpaybrasil.com/primeiros-passos/erros.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar o pagamento por Pix no checkout.

1. Criar a cobrança Pix pelo servidor e devolver ao front-end o código copia e cola e o QR Code.
2. Receber o webhook de cobrança, atualizar o pedido e liberar a compra só quando o pagamento for confirmado.
3. Tratar Pix expirado e os erros de validação conforme a página de erros.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

### Cartão de crédito com 3D Secure

Cartão parcelado, 3D Secure gerenciado e cartão salvo para recompra.

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md)
* [https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md)
* [https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md)
* [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md)
* [https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md)
* [https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
* [https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar o pagamento com cartão de crédito.

1. Criar a cobrança com cartão, com parcelamento quando houver.
2. Tratar o status de autenticação 3D Secure gerenciado, levando o comprador ao endereço de autenticação e acompanhando o desfecho.
3. Oferecer o cartão salvo para a próxima compra, seguindo as regras do cofre de cartões.
4. Mostrar ao comprador uma mensagem clara em caso de recusa, sem expor detalhes técnicos.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

### Receptor de webhooks

Endpoint que recebe, valida e processa os eventos da Finvia sem duplicar efeitos.

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/saque.md](https://docs.fastpaybrasil.com/guias/webhooks/saque.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/conta.md](https://docs.fastpaybrasil.com/guias/webhooks/conta.md)
* [https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md](https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md)
* [https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: criar o endpoint que recebe os webhooks da Finvia.

1. Responder rápido e processar o evento de forma assíncrona.
2. Registrar cada evento recebido e ignorar repetições, como explica a seção de idempotência no recebimento de webhooks.
3. Atualizar pedidos, assinaturas e saques conforme o catálogo de eventos.
4. Cadastrar o endpoint pela API, seguindo a referência de webhooks.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

### Assinaturas

Planos, assinatura com trial, renovação automática, falhas e cancelamento.

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
* [https://docs.fastpaybrasil.com/guias/assinaturas/planos.md](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md)
* [https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
* [https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md)
* [https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar a cobrança recorrente.

1. Criar os planos e a assinatura do cliente, com trial quando o plano tiver.
2. Liberar e bloquear o acesso do cliente de acordo com os eventos de assinatura.
3. Permitir troca de plano e cancelamento pelas rotas documentadas.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

### Subcontas, split e saques

Marketplace ou plataforma com subcontas, divisão de pagamentos e saques por Pix.

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/split.md](https://docs.fastpaybrasil.com/guias/fast-connect/split.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/saques.md](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/conta.md](https://docs.fastpaybrasil.com/guias/webhooks/conta.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar o modelo de conta master com subcontas.

1. Cadastrar a subconta, enviar os documentos e acompanhar a análise pelos webhooks de conta.
2. Criar cobranças com split e conferir o valor de cada recebedor conforme a página de cálculo do split.
3. Solicitar saques por Pix da subconta e tratar o resultado.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

### Estorno, disputas e saldo

Estorno total ou parcial, bloqueio cautelar, chargeback, MED e consulta de saldo.

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/guias/estorno.md](https://docs.fastpaybrasil.com/guias/estorno.md)
* [https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md)
* [https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md)
* [https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar o pós-venda financeiro.

1. Permitir estorno pelo sistema de pedidos, respeitando as regras de prazo e de valor.
2. Tratar os eventos de bloqueio, chargeback e MED, avisando o time responsável.
3. Mostrar o saldo disponível, a liberar e reservado da conta.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

### Revisar uma integração e preparar a homologação

Auditoria do código atual contra a documentação e o roteiro de homologação.

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
* [https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md](https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md)
* [https://docs.fastpaybrasil.com/primeiros-passos/erros.md](https://docs.fastpaybrasil.com/primeiros-passos/erros.md)
* [https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: revisar a integração que já existe neste projeto.

1. Comparar cada chamada à API da Finvia com a documentação e apontar divergências de rota, campo, status ou tratamento de erro.
2. Conferir os itens do checklist de go-live e marcar o que falta.
3. Listar os testes do roteiro de homologação que o código ainda não cobre.

Não altere o código antes de apresentar a lista de problemas encontrados.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

## Atalhos em todas as páginas

No topo de cada página da documentação há um menu com atalhos para assistentes de IA:

| Atalho | O que faz |
| - | - |
| Copiar página | Copia a página em Markdown, pronta para colar no Claude Code, no Codex, no Gemini ou em qualquer outro assistente |
| Ver como Markdown | Abre a versão em texto da página, que também pode ser enviada como link |
| Abrir no ChatGPT, no Claude, no Gemini (AI Studio) ou no Perplexity | Abre o assistente já com a página como contexto, para você fazer perguntas sobre ela |
| Conectar ao Cursor ou ao VS Code | Instala o servidor MCP da documentação no editor |

Para levar uma página específica ao assistente, como a de [criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md), use **Copiar página** e escreva o pedido logo abaixo do texto colado.

## Documentação inteira para o assistente

Dois endereços entregam a documentação em formato próprio para IA:

| Endereço | Conteúdo |
| - | - |
| [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) | Índice de todas as páginas, com links para a versão em Markdown de cada uma |
| [https://docs.fastpaybrasil.com/llms-full.txt](https://docs.fastpaybrasil.com/llms-full.txt) | A documentação inteira num só arquivo de texto |

Com o índice, o assistente encontra sozinho a página de que precisa. Basta incluir o endereço no pedido, como os prompts acima já fazem.

## Servidor MCP

O servidor MCP deixa o assistente pesquisar a documentação da Finvia sempre que precisar, sem você copiar nada. O endereço é:

```text theme={null}
https://docs.fastpaybrasil.com/mcp
```

No Claude Code, adicione com:

```bash theme={null}
claude mcp add --transport http finvia-docs https://docs.fastpaybrasil.com/mcp
```

No Cursor e no VS Code, use o atalho **Conectar** do menu de cada página. Em outros assistentes, como Codex e Gemini CLI, adicione um servidor MCP remoto do tipo HTTP com o endereço acima, seguindo a documentação da ferramenta.

## Veja também

> [card] [Sua primeira cobrança](https://docs.fastpaybrasil.com/primeiros-passos/primeira-cobranca.md)
>
> O passo a passo da primeira chamada, para conferir o que o assistente fez.

> [card] [Roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> Os testes que a integração precisa passar antes de ir para produção.


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