> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Integração com IA
> Forneça o contexto certo da documentação da Pagou antes de agentes de IA gerarem código.
Copie este prompt em qualquer agente de IA:
```text Contexto Pagou para IA theme={null}
Você é um engenheiro sênior construindo uma integração Pagou em produção.
Fontes de verdade:
- Docs rápidas: https://developer.pagou.ai/llms.txt
- Docs completas: https://developer.pagou.ai/llms-full.txt
- OpenAPI v2: https://developer.pagou.ai/api-reference/openapi-v2.json
- Base URLs: https://api.pagou.ai e https://api.sandbox.pagou.ai
Regras:
- Mantenha chaves secretas da Pagou apenas no servidor. Use env vars.
- Valide endpoints, campos, status e formatos de webhook no OpenAPI antes de codar.
- Não invente endpoints, campos ou fluxos não documentados.
- Valores na API v2 são em centavos.
- Sempre inclua external_ref e idempotência em escritas.
- Use Payment Element / SDK v3 para cartões. Envie ao back-end apenas tokens pgct_.
- Implemente webhooks reais, deduplique pelo id do evento no topo e processe de forma assíncrona.
- Roteie pagamentos por event=transaction + data.event_type.
- Roteie assinaturas por event=subscription + data.event_type.
- Roteie transferências pelo type no topo.
- Libere pedidos, acesso e estado de saque apenas por webhook confirmado ou estado reconciliado no servidor.
- Use polling/GET apenas para reconciliação, suporte ou recuperação. Nunca use polling como fluxo principal.
```
## Referência da documentação
`llms.txt` — encontre a página certa rapidamente
`llms-full.txt` — docs completa offline
OpenAPI — endpoints, campos, webhooks
## Configurar por agente
Adicione ao `CLAUDE.md` na raiz do projeto:
```markdown theme={null}
## Integração Pagou
- Fontes de verdade: https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json
- Mantenha chaves secretas da Pagou apenas no servidor e use env vars
- Valide endpoints, campos, status e webhooks no OpenAPI; não invente campos não documentados
- Valores na API v2 são em centavos
- Sempre inclua external_ref e idempotência em escritas
- Use Payment Element / SDK v3 para cartões e envie ao back-end apenas tokens pgct_
- Implemente webhooks reais, deduplique pelo id no topo, processe de forma assíncrona e evite polling como fluxo principal
- Libere pedidos, assinaturas e transferências apenas por webhook confirmado ou estado reconciliado no servidor
```
[Template CLAUDE.md completo](/pt/start-here/claude-md-template)
Adicione ao `AGENTS.md` na raiz do projeto:
```markdown theme={null}
## Integração Pagou
- Fontes de verdade: https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json
- Mantenha chaves secretas da Pagou apenas no servidor e use env vars
- Valide endpoints, campos, status e webhooks no OpenAPI; não invente campos não documentados
- Valores na API v2 são em centavos
- Sempre inclua external_ref e idempotência em escritas
- Use Payment Element / SDK v3 para cartões e envie ao back-end apenas tokens pgct_
- Implemente webhooks reais, deduplique pelo id no topo, processe de forma assíncrona e evite polling como fluxo principal
- Libere pedidos, assinaturas e transferências apenas por webhook confirmado ou estado reconciliado no servidor
```
Ou rode com contexto inline:
```bash theme={null}
codex "Leia https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json. Crie checkout Pix com chamadas Pagou apenas no back-end, external_ref, endpoint de webhook, deduplicação de evento e GET apenas para reconciliação."
```
Adicione ao `.cursorrules` na raiz do projeto:
```markdown theme={null}
## Integração Pagou
- Fontes de verdade: https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json
- Mantenha chaves secretas da Pagou apenas no servidor e use env vars
- Valide endpoints, campos, status e webhooks no OpenAPI; não invente campos não documentados
- Valores na API v2 são em centavos
- Sempre inclua external_ref e idempotência em escritas
- Use Payment Element / SDK v3 para cartões e envie ao back-end apenas tokens pgct_
- Implemente webhooks reais, deduplique pelo id no topo, processe de forma assíncrona e evite polling como fluxo principal
- Libere pedidos, assinaturas e transferências apenas por webhook confirmado ou estado reconciliado no servidor
```
[Template .cursorrules completo](/pt/start-here/cursorrules-template)
Cole o Contexto Pagou para IA acima no início do chat e faça sua pergunta. Exija que o agente implemente webhooks reais, deduplique eventos, mantenha segredos no servidor e evite polling como fluxo principal.
Se o agente não conseguir acessar URLs, cole a seção relevante do [llms-full.txt](https://developer.pagou.ai/llms-full.txt) diretamente.
Comece com esta primeira mensagem. Ela força limites de back-end, webhooks e campos documentados:
```text Prompt Lovable para integração Pagou theme={null}
Você é um engenheiro sênior construindo uma integração Pagou em produção dentro do Lovable.
Use somente estas fontes de verdade da Pagou:
- Docs completas: https://developer.pagou.ai/llms-full.txt
- OpenAPI v2: https://developer.pagou.ai/api-reference/openapi-v2.json
- Base URL produção: https://api.pagou.ai
- Base URL sandbox: https://api.sandbox.pagou.ai
Escopo:
- Clientes: criar, listar e consultar clientes
- Transações: Pix, voucher/pagamento local, cartão, listagem, consulta e reembolso
- Assinaturas: criar, listar, consultar, atualizar e cancelar cobrança recorrente com cartão
- Transferências: criação, listagem, consulta e cancelamento de Pix Out
- Webhooks: eventos de pagamento, assinatura e transferência
- Cartão no front-end: Payment Element / SDK v3 para tokenização segura
Regras obrigatórias:
- Nunca exponha token secreto da Pagou no browser.
- Toda chamada para a API Pagou deve sair de uma rota de back-end, server function ou server action segura.
- Use variáveis de ambiente para credenciais e base URL.
- Use sandbox primeiro. A troca para produção deve ser apenas configuração.
- Use Payment Element / SDK v3 para coletar cartão. Envie ao back-end apenas o token `pgct_`.
- Nunca manipule número de cartão diretamente.
- Valores na API Pagou v2 são em centavos. Exemplo: R$ 49,00 = `4900`.
- Sempre envie um `external_ref` determinístico em criações e escritas sensíveis.
- Use idempotência em criações, reembolsos, ações de assinatura e transferências.
- Não invente endpoints, campos, status ou formatos de webhook. Valide no OpenAPI primeiro.
Arquitetura webhook-first:
- Implemente um endpoint real de webhook, não apenas polling.
- Responda `2xx` rapidamente no endpoint de webhook.
- Não execute lógica pesada antes de responder ao webhook.
- Persista ou enfileire o payload e processe de forma assíncrona.
- Faça deduplicação pelo `id` do evento no topo do payload.
- Eventos de pagamento usam `event: "transaction"` e o evento concreto em `data.event_type`.
- Eventos de assinatura usam `event: "subscription"` e o evento concreto em `data.event_type`.
- Eventos de transferência usam `type` no topo, como `payout.transferred` ou `payout.failed`.
- Use polling/GET apenas para reconciliação, tela de suporte ou recuperação de estado incerto. Não use polling como fluxo principal.
Liberação e estado:
- Nunca libere pedido usando apenas mensagem de sucesso do browser.
- Libere pedidos Pix, voucher e cartão apenas depois de `transaction.paid` ou estado pago reconciliado.
- Para cartão, trate `next_action` / 3DS quando retornar.
- Para voucher/pagamento local, as instruções podem vir na criação ou depois por webhook.
- Para assinaturas, use webhooks para eventos created, started, renewed, updated, canceled, payment_failed, past_due, trial_will_end e chargeback_received.
- Para transferências, use o status do recurso como estado operacional e eventos de webhook como transições.
Tratamento de erro:
- 4xx: corrija requisição ou permissão. Não faça retry automático.
- 409: reconcilie o recurso existente antes de criar outro.
- 429, 5xx, timeout: faça retry com backoff exponencial e jitter apenas quando a escrita for idempotente.
- Sempre logue `requestId` quando a API retornar.
- Mostre mensagens seguras ao usuário. Não exponha detalhes internos de provedor nem segredos.
Ao gerar código:
1. Crie uma arquitetura clara com front-end + back-end/server functions.
2. Mantenha todos os segredos da Pagou no servidor.
3. Implemente endpoint de webhook e deduplicação de eventos.
4. Use estado confirmado por webhook ou reconciliado no servidor para ações finais de negócio.
5. Inclua variáveis de ambiente necessárias.
6. Cite o endpoint usado em cada fluxo.
7. Valide campos de request e response no OpenAPI.
8. Se um comportamento não estiver documentado, diga que não está documentado e recomende contato com o suporte Pagou usando o `requestId`.
Construa: [descreva o app e os fluxos Pagou necessários]
```
Substitua `[descreva seu app]` pelo que você quer construir.
## Prompts completos
Copie qualquer um destes direto no seu agente de IA:
```text theme={null}
Leia https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json
Construa um fluxo de checkout Pix:
1. Back-end/server function apenas: POST /v2/transactions com method=pix, valor em centavos e external_ref
2. Front-end: exiba apenas os campos Pix voltados ao comprador retornados pelo back-end
3. Webhook: implemente POST /webhooks/pagou, deduplique pelo id de topo e roteie event=transaction por data.event_type
4. Liberação: atualize o pedido apenas depois de transaction.paid ou estado pago reconciliado
5. Reconciliação: use GET /v2/transactions/{id} apenas para recuperação/suporte, não como fluxo principal
Use env vars para API keys. Nunca exponha credenciais Pagou no front-end. Valide todos os campos no OpenAPI.
```
```text theme={null}
Leia https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json
Construa um fluxo de checkout de cartão:
1. Front-end: carregue Payment Element de https://js.pagou.ai/payments/v3.js e monte campos hospedados de cartão
2. No submit: chame elements.submit() e envie ao back-end apenas o token pgct_
3. Back-end/server function apenas: POST /v2/transactions com method=credit_card, valor em centavos, token, installments e external_ref
4. 3DS: se a resposta do back-end tiver next_action, continue o challenge pelo fluxo do SDK
5. Webhook: roteie event=transaction por data.event_type e atualize o pedido apenas depois de webhook ou reconciliação no servidor
6. Reconciliação: use GET /v2/transactions/{id} apenas depois de estado incerto no browser/rede
Use env vars para API keys. Nunca exponha segredos nem manipule número de cartão diretamente. Valide todos os campos no OpenAPI.
```
```text theme={null}
Leia https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json
Construa um fluxo de assinatura:
1. Back-end/server function apenas: crie ou consulte o cliente com /v2/customers
2. Front-end: use Payment Element em modo subscription e envie ao back-end apenas o token pgct_
3. Back-end: POST /v2/subscriptions com customer_id, token, valor em centavos, interval, interval_count, external_ref/metadata se necessário
4. Webhook: implemente POST /webhooks/pagou, deduplique pelo id de topo e roteie event=subscription por data.event_type
5. Estado: libere ou remova acesso pelo status da assinatura e webhooks de assinatura, não pelo estado do browser
6. Reconciliação: use GET /v2/subscriptions/{id} apenas para recuperação/suporte ou estado incerto
Trate subscription.created, subscription.started, subscription.renewed, subscription.updated, subscription.canceled, subscription.payment_failed, subscription.past_due, subscription.trial_will_end e subscription.chargeback_received.
Use env vars para API keys. Nunca exponha credenciais Pagou no front-end. Valide todos os campos no OpenAPI.
```
```text theme={null}
Leia https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json
Construa um endpoint de webhook:
1. POST /webhooks/pagou - aceite body JSON e retorne 200 com {"received": true} rapidamente
2. Persista ou enfileire o payload bruto antes do processamento assíncrono
3. Deduplique pelo campo "id" no topo (mesmo evento pode ser enviado múltiplas vezes)
4. Roteie eventos de pagamento por event=transaction e data.event_type
5. Roteie eventos de assinatura por event=subscription e data.event_type
6. Roteie eventos de transferência pelo type no topo, como payout.transferred, payout.failed, payout.rejected, payout.canceled
7. Execute lógica pesada em background, não antes da resposta HTTP
Armazene IDs de eventos processados para prevenir duplicação. Não use polling como caminho principal de atualização de estado.
```
```text theme={null}
Leia https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json
Construa um fluxo de transferência Pix Out:
1. Back-end/server function apenas: POST /v2/transfers com dados Pix do recebedor, valor em centavos e external_ref
2. Webhook: roteie eventos de transferência pelo type no topo, incluindo payout.transferred, payout.failed, payout.rejected e payout.canceled
3. Estado: atualize o status do payout pelo webhook/status do recurso, não por polling no front-end
4. Reconciliação: use GET /v2/transfers/{id} apenas se o webhook atrasar ou ficar incerto
5. Cancelamento: POST /v2/transfers/{id}/cancel apenas quando o status atual do recurso permitir
Use env vars para API keys. Nunca exponha credenciais Pagou no front-end. Valide todos os campos no OpenAPI.
```
## Dicas para agentes
* Mantenha API keys apenas no servidor, use env vars
* Nunca logue tokens de cartão ou chaves Pix
* Valide origem do webhook antes de processar
* Use HTTPS em todo lugar
* Teste em sandbox primeiro, mesmo código funciona em prod
* Use ngrok para receber webhooks localmente
* Sempre envie external\_ref para idempotência
* Reconcilie com GET se webhook falhar
## Leia a seguir
* [Início rápido SDK TypeScript](/pt/sdks/typescript/quickstart)
* [Receber pagamentos Pix](/pt/payments/pix/accept-payments)
* [Visão geral de Webhooks](/pt/webhooks/overview)