> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create your first successful v2 sandbox transaction with the minimum required setup.

This page is the shortest backend path from credentials to a working sandbox Pix payment.

## Prerequisites

* A sandbox token
* Access to `https://api.sandbox.pagou.ai`
* A stable order ID from your system to reuse as `external_ref`
* An HTTPS webhook endpoint or a temporary local plan for reconciliation

## Step 1: verify authentication

```bash theme={null}
curl --request GET \
  --url https://api.sandbox.pagou.ai/v2/transactions \
  --header "Authorization: Bearer YOUR_SANDBOX_TOKEN"
```

If this returns `200`, your auth and network path are ready.

## Step 2: create a Pix transaction

```bash theme={null}
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://shop.example/webhooks/pagou",
    "buyer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      }
    },
    "products": [
      {
        "name": "Starter order",
        "price": 1500,
        "quantity": 1
      }
    ]
  }'
```

## Example response

```json theme={null}
{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
    "status": "pending",
    "method": "pix",
    "amount": 1500,
    "base_price": 1500,
    "currency": "BRL",
    "pix": {
      "qr_code": "000201010212...",
      "expiration_date": "2026-03-16T14:15:00.000Z",
      "receipt_url": null
    },
    "created_at": "2026-03-16T14:00:00.000Z",
    "updated_at": "2026-03-16T14:00:00.000Z",
    "paid_at": null
  }
}
```

## Step 3: persist identifiers

Store at least:

* your `external_ref`
* the Pagou transaction `id`
* the current `status`
* the `requestId`

## Step 4: use webhooks for final state

Return `200 OK` quickly and process asynchronously.

```ts theme={null}
app.post("/webhooks/pagou", async (req, reply) => {
  const payload = req.body as { id?: string };

  if (!payload.id) {
    return reply.code(400).send({ error: "missing_event_id" });
  }

  reply.code(200).send({ received: true });
  await queue.enqueue(payload);
});
```

## Step 5: reconcile when you are unsure

```bash theme={null}
curl --request GET \
  --url https://api.sandbox.pagou.ai/v2/transactions/018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f \
  --header "Authorization: Bearer YOUR_SANDBOX_TOKEN"
```

## Common error

Status `409`

```json theme={null}
{
  "type": "https://api.pagou.ai/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A transaction with external_ref order_1001 already exists."
}
```

Fix: reuse the same `external_ref` only for the same logical payment attempt. If the network outcome is unclear, reconcile before creating a new transaction.

## TypeScript SDK equivalent

```ts theme={null}
import { Client } from "@pagouai/api-sdk";

const client = new Client({
  apiKey: process.env.PAGOU_API_KEY!,
  environment: "sandbox",
});

const created = await client.transactions.create({
  external_ref: "order_1001",
  amount: 1500,
  currency: "BRL",
  method: "pix",
  notify_url: "https://shop.example/webhooks/pagou",
  buyer: {
    name: "Ada Lovelace",
    email: "ada@example.com",
    document: { type: "CPF", number: "12345678901" },
  },
  products: [{ name: "Starter order", price: 1500, quantity: 1 }],
});
```

## Next steps

* [Authentication](/start-here/authentication)
* [Idempotency](/start-here/idempotency)
* [Accept Pix Payments](/payments/pix/accept-payments)