> ## 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.

# Receber pagamentos Pix

> Crie uma cobrança Pix, devolva os dados de pagamento ao comprador e opere o fluxo com webhooks.

Use esta página para o caminho de escrita que inicia uma cobrança Pix.

## Fluxo feliz

1. Crie uma transação com `method: "pix"`.
2. Devolva os dados do QR code Pix ao comprador.
3. Persista o `id` da transação na Pagou e o seu `external_ref`.
4. Aguarde a entrega do webhook.
5. Reconcilie apenas quando o estado do pagamento estiver incerto.

## Exemplo de requisição

```bash theme={null}
curl --request POST \
  --url https://api.pagou.ai/v2/transactions \
  --header "Authorization: Bearer SEU_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
      }
    ]
  }'
```

## Exemplo de resposta

```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
  }
}
```

## Erro comum

Status `422`

```json theme={null}
{
  "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"
    }
  ]
}
```

Como corrigir: valide os dados do comprador antes de chamar a Pagou. Não trate `pending` como final. O pagamento só está liquidado após um status terminal como `paid`.

## O que o front-end deve receber

Devolva apenas os dados Pix necessários para o comprador, como:

* `id` da transação
* `status` atual
* `pix.qr_code`
* `pix.expiration_date`

## Próximos passos

* [Reembolsos Pix](/pt/payments/pix/refunds)
* [Reconciliação Pix](/pt/payments/pix/reconciliation)
* [Eventos de pagamento](/pt/webhooks/payment-events)