Skip to main content
Use this page for the write path that starts a Pix collection.

​
Happy path

  1. Create a transaction with method: "pix".
  2. Return the Pix QR code data to the buyer.
  3. Persist the Pagou transaction id and your external_ref.
  4. Wait for webhook delivery.
  5. Reconcile only when the payment state is uncertain.

​
Example request

curl --request POST \
  --url https://api.pagou.ai/v2/transactions \
  --header "Authorization: Bearer YOUR_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
      }
    ]
  }'

​
Example response

{
  "success": true,
  "requestId": "req_1201",
  "data": {
    "id": "tr_1001",
    "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
  }
}

​
Common error

Status 422 
{
  "type": "https://api.pagou.ai/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request contains invalid data.",
  "errors": [
    {
      "field": "buyer.document.number",
      "message": "Invalid document number",
      "code": "invalid_string"
    }
  ]
}
Fix: validate buyer data before calling Pagou. Do not treat pending as final. The payment is only settled after a terminal status such as paid.

​
What your frontend should receive

Return only the buyer-facing Pix data your frontend needs, such as:
  • transaction id
  • current status
  • pix.qr_code
  • pix.expiration_date

​
Next steps