This page is for backend engineers who want the fastest path to a working Pagou sandbox integration.
Before you begin
- A Pagou sandbox token
- Access to
https://api-sandbox.pagou.ai
- A place to store your own order ID or request ID as
external_ref
Time to complete: about 10 to 15 minutes.
Step 1: pick one authentication method
Bearer token is the default recommendation for new integrations:
curl --request GET \
--url https://api-sandbox.pagou.ai/v2/transactions \
--header "Authorization: Bearer YOUR_SANDBOX_TOKEN"
Step 2: create a Pix transaction
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",
"notify_url": "https://merchant.example/webhooks/pagou",
"buyer": {
"name": "Ada Lovelace",
"email": "ada@example.com",
"document": {
"type": "CPF",
"number": "12345678901"
}
},
"products": [
{
"name": "Starter order",
"price": 1500,
"quantity": 1
}
]
}'
{
"success": true,
"requestId": "req_123",
"data": {
"id": "trx_123",
"status": "pending",
"method": "pix",
"amount": 1500
}
}
Step 3: store Pagou identifiers
Persist at least:
- your
external_ref
- Pagou transaction
id
- current transaction
status
requestId for support and operational debugging
Step 4: treat webhooks as primary status updates
Expose an HTTPS endpoint and acknowledge immediately:
app.post("/webhooks/pagou", async (req, reply) => {
const event = req.body as { id: string };
reply.code(200).send({ received: true });
await queue.enqueue(event);
});
Step 5: reconcile if you are unsure
curl --request GET \
--url https://api-sandbox.pagou.ai/v2/transactions/trx_123 \
--header "Authorization: Bearer YOUR_SANDBOX_TOKEN"
TypeScript equivalent
import { Pagou } from "@pagouai/api-sdk";
const client = new Pagou({
baseUrl: "https://api-sandbox.pagou.ai",
token: process.env.PAGOU_TOKEN,
});
const transaction = await client.transactions.create({
external_ref: "order_1001",
amount: 1500,
currency: "BRL",
method: "pix",
notify_url: "https://merchant.example/webhooks/pagou",
buyer: {
name: "Ada Lovelace",
email: "ada@example.com",
document: {
type: "CPF",
number: "12345678901",
},
},
products: [{ name: "Starter order", price: 1500, quantity: 1 }],
});
What to do next
