Overview - Pagou Developer Docs

Use this section if you are designing a new Pagou integration or replacing a legacy one.

Who this is for

Backend engineers who own payment and payout APIs
Platform engineers who own auth, retries, and webhook ingestion
Product and operations teams who need a shared lifecycle model

What you can build

Pix collections with QR code delivery and webhook confirmation
Voucher payments with local instructions such as Boleto, SPEI, Mercado Pago, Webpay, CODI, and PSE
Card payments with Payment Element and 3D Secure
Recurring subscriptions by card or Pix Automático, with renewal webhooks
Pix Out transfers with operator-safe cancellation and reconciliation
Customer records for reusable buyer profiles

Recommended integration model

Create payments and transfers only from your backend.
Use external_ref as your stable idempotency key for creates.
Treat webhooks as the primary source of truth for async state changes.
Reconcile with GET /v2/transactions/{id} or GET /v2/transfers/{id} when the outcome is unclear.

Public surface

Capability	Main endpoints	Notes
Authentication	all v2 routes	Choose one auth scheme and keep it consistent
Customers	`POST /v2/customers`, `GET /v2/customers`, `GET /v2/customers/{id}`	Optional reusable buyer records
Payments	`POST /v2/transactions`, `GET /v2/transactions/{id}`, `PUT /v2/transactions/{id}/refund`	Pix, voucher, and card flows share the transactions API
Subscriptions	`POST /v2/subscriptions`, `GET /v2/subscriptions/{id}`, `POST /v2/subscriptions/{id}/cancel`	Recurring billing lifecycle, by card or Pix Automático
Payouts	`POST /v2/transfers`, `GET /v2/transfers/{id}`, `POST /v2/transfers/{id}/cancel`	Pix Out transfer lifecycle
Webhooks	payment, subscription, and transfer event delivery	Build one ingestion pipeline with deduplication
SDK	`@pagouai/api-sdk`	Server-side TypeScript client

Before you build

Get separate sandbox and production credentials.
Decide where you will store external_ref, Pagou IDs, and requestId values.
Expose an HTTPS webhook endpoint before moving to production.
Keep frontend code away from secret credentials.

Read next