Skip to main content

Pagou Gateway v2

​
Welcome to the Pagou API.

Everything you need to integrate Pix collections, card payments, Payment Element, Pix transfers, webhooks, and operational reconciliation lives in one developer-first reference.

Start with v2, use one auth scheme, send stable external_ref values, and let webhooks drive asynchronous state.

Use Payment Element for hosted fields, tokenization, and 3DS orchestration, then create transactions from your backend.

Write through API calls, acknowledge webhooks fast, and reconcile with GET endpoints when outcomes are uncertain.

​
Main content

Make your first API request

Go from credentials to your first successful v2 sandbox transaction with the shortest possible setup.

Authentication

Standardize one auth strategy for production and validate access before you implement money movement.

Sandbox and production

Understand base URLs, credential separation, and the deployment model for safe cutover.

Pix payments

Create Pix charges, return QR code data, wait for webhooks, and support refunds plus reconciliation.

Card payments

Use the recommended card flow, understand transaction states, and model refunds correctly.

Payment Element

Implement hosted card fields, frontend tokenization, and 3DS with a production-ready browser flow.

Pix transfers

Create, list, cancel, and reconcile outbound Pix transfers using the same v2 operating model.

Webhooks

Build one resilient consumer for payment and transfer events with fast acknowledgement and deduplication.

TypeScript SDK

Use the official SDK with real examples for transactions, transfers, retries, pagination, and typed errors.

API reference

Browse the generated OpenAPI contract for every supported public v2 endpoint.

Legacy v1 archive

Keep older integrations running and map legacy flows to the recommended v2 model.

Changelog

Track documentation updates and public integration changes that affect implementation.

Start Here

See the full integration map, then move through quickstart, authentication, idempotency, errors, and go-live guidance.

Payments

Model customers, transaction states, Pix flows, card flows, and refund handling from one payments section.

Payouts

Handle Pix transfers with create, list, cancel, status, and reconciliation guides.

Frontend

Build the browser side of card acceptance with hosted fields, events, and 3DS behavior.

​
Quick sandbox example

curl --request POST \
  --url https://api-sandbox.pagou.ai/v2/transactions \
  --header "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "external_ref": "order_1001",
    "amount": 1500,
    "currency": "BRL",
    "method": "pix",
    "buyer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      }
    },
    "products": [
      {
        "name": "Starter order",
        "price": 1500,
        "quantity": 1
      }
    ]
  }'
Production baseline: authenticate with one method, send a stable external_ref, acknowledge webhooks in milliseconds, and reconcile any uncertain state with GET /v2/transactions/{id} or GET /v2/transfers/{id}.