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
- Card payments with Payment Element and 3D Secure
- 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_refas your stable idempotency key for creates. - Treat webhooks as the primary source of truth for async state changes.
- Reconcile with
GET /v2/transactions/{id}orGET /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 and card flows share the transactions API |
| Payouts | POST /v2/transfers, GET /v2/transfers/{id}, POST /v2/transfers/{id}/cancel | Pix Out transfer lifecycle |
| Webhooks | payment 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, andrequestIdvalues. - Expose an HTTPS webhook endpoint before moving to production.
- Keep frontend code away from secret credentials.