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

# Visão geral

> Entenda a superfície pública suportada da Pagou.ai antes de iniciar a integração.

Use esta seção se você está desenhando uma nova integração com a Pagou ou substituindo uma integração legada.

## Para quem é

* Engenheiros de back-end que cuidam das APIs de pagamento e payout
* Engenheiros de plataforma que cuidam de autenticação, retentativas e ingestão de webhook
* Times de produto e operação que precisam de um modelo único de ciclo de vida

## O que você pode construir

* Cobranças Pix com entrega de QR code e confirmação por webhook
* Pagamentos por voucher com instruções locais como Boleto, SPEI, Mercado Pago, Webpay, CODI e PSE
* Pagamentos com cartão usando Payment Element e 3D Secure
* Assinaturas recorrentes com cartão salvo e webhooks de renovação
* Transferências Pix Out com cancelamento seguro para operação e reconciliação
* Registros de clientes para perfis reutilizáveis de comprador

## Modelo recomendado de integração

1. Crie pagamentos e transferências apenas pelo seu back-end.
2. Use `external_ref` como chave estável de idempotência nas criações.
3. Trate webhooks como fonte principal de verdade para mudanças assíncronas de estado.
4. Reconcilie com `GET /v2/transactions/{id}` ou `GET /v2/transfers/{id}` quando o resultado estiver incerto.

## Superfície pública

| Capacidade     | Principais endpoints                                                                         | Observação                                                 |
| -------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Autenticação   | todas as rotas v2                                                                            | Escolha um esquema de autenticação e mantenha consistência |
| Clientes       | `POST /v2/customers`, `GET /v2/customers`, `GET /v2/customers/{id}`                          | Registros opcionais de comprador                           |
| Pagamentos     | `POST /v2/transactions`, `GET /v2/transactions/{id}`, `PUT /v2/transactions/{id}/refund`     | Pix, voucher e cartão compartilham a API de transações     |
| Assinaturas    | `POST /v2/subscriptions`, `GET /v2/subscriptions/{id}`, `POST /v2/subscriptions/{id}/cancel` | Ciclo de vida de cobrança recorrente com cartão            |
| Transferências | `POST /v2/transfers`, `GET /v2/transfers/{id}`, `POST /v2/transfers/{id}/cancel`             | Ciclo de vida de Pix Out                                   |
| Webhooks       | eventos de pagamento, assinatura e transferência                                             | Monte um pipeline único com deduplicação                   |
| SDK            | `@pagouai/api-sdk`                                                                           | Cliente TypeScript para servidor                           |

## Antes de construir

* Tenha credenciais separadas para sandbox e produção.
* Defina onde armazenar `external_ref`, IDs da Pagou e valores de `requestId`.
* Exponha um endpoint HTTPS de webhook antes de ir para produção.
* Não coloque credenciais secretas no front-end.

## Leia a seguir

* [Início rápido](/pt/start-here/quickstart)
* [Autenticação](/pt/start-here/authentication)
* [Fundamentos de webhook](/pt/start-here/webhooks)
* [Visão geral de pagamentos](/pt/payments/overview)
* [Visão geral de assinaturas](/pt/subscriptions/overview)