Para quem é
- Engenheiros de back-end que cuidam das APIs de pagamento e payout
- Engenheiros de plataforma que cuidam de auth, retries 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 com cartão usando Payment Element e 3D Secure
- 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
- Crie pagamentos e transferências apenas pelo seu back-end.
- Use
external_refcomo chave estável de idempotência nas criações. - Trate webhooks como fonte principal de verdade para mudanças assíncronas de estado.
- Reconcilie com
GET /v2/transactions/{id}ouGET /v2/transfers/{id}quando o resultado estiver incerto.
Superfície pública
| Capacidade | Principais endpoints | Observação |
|---|---|---|
| Authentication | todas as rotas v2 | Escolha um esquema de auth e mantenha consistência |
| Customers | POST /v2/customers, GET /v2/customers, GET /v2/customers/{id} | Registros opcionais de comprador |
| Payments | POST /v2/transactions, GET /v2/transactions/{id}, PUT /v2/transactions/{id}/refund | Pix e cartão compartilham a API de transactions |
| Payouts | POST /v2/transfers, GET /v2/transfers/{id}, POST /v2/transfers/{id}/cancel | Ciclo de vida de Pix Out |
| Webhooks | entrega de eventos de pagamento 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 derequestId. - Exponha um endpoint HTTPS de webhook antes de ir para produção.
- Não coloque credenciais secretas no front-end.