Skip to main content
Use this page when you are implementing Pix collections as the primary payment method.

​
Happy path

  1. Create a transaction with method: "pix".
  2. Return the Pix payment data to the buyer experience.
  3. Persist the Pagou transaction ID.
  4. Wait for the webhook event.
  5. Reconcile with GET /v2/transactions/{id} if the status is uncertain.

​
Create the transaction

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
      }
    ]
  }'

​
What to return to your frontend

Return at least:
  • transaction id
  • current status
  • any Pix display data exposed in the response payload
Your frontend should not derive state transitions locally. It should react to your backend, which in turn reacts to Pagou webhooks and reconciliation.

​
Common failure modes

  • Duplicate create request with a different intent: fix your external_ref handling.
  • Waiting for frontend polling only: move status truth to webhooks.
  • Treating pending as final: keep the order open until a terminal status arrives.