Pular para o conteúdo principal
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

CapacidadePrincipais endpointsObservação
Autenticaçãotodas as rotas v2Escolha um esquema de autenticação e mantenha consistência
ClientesPOST /v2/customers, GET /v2/customers, GET /v2/customers/{id}Registros opcionais de comprador
PagamentosPOST /v2/transactions, GET /v2/transactions/{id}, PUT /v2/transactions/{id}/refundPix, voucher e cartão compartilham a API de transações
AssinaturasPOST /v2/subscriptions, GET /v2/subscriptions/{id}, POST /v2/subscriptions/{id}/cancelCiclo de vida de cobrança recorrente com cartão
TransferênciasPOST /v2/transfers, GET /v2/transfers/{id}, POST /v2/transfers/{id}/cancelCiclo de vida de Pix Out
Webhookseventos de pagamento, assinatura e transferênciaMonte um pipeline único com deduplicação
SDK@pagouai/api-sdkCliente 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