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

# Criar cobrança PIX

> Gere um PIX avulso com QR Code e código copia-e-cola.

Cria uma cobrança PIX avulsa. Requer a permissão `pix:write`.

<ParamField header="Idempotency-Key" type="string">
  Recomendado. Até 128 caracteres e escopo por loja. Evita cobrança duplicada em retries.
</ParamField>

<ParamField body="customer.email" type="string" required>
  E-mail válido do pagador.
</ParamField>

<ParamField body="customer.name" type="string" required>
  Nome completo do pagador.
</ParamField>

<ParamField body="customer.document" type="string" required>
  CPF ou CNPJ, com ou sem formatação.
</ParamField>

<ParamField body="customer.phone" type="string">
  Telefone do pagador.
</ParamField>

<ParamField body="amount" type="number" required>
  Valor em reais, não em centavos.
</ParamField>

<ParamField body="currency" type="string">
  Use `BRL`.
</ParamField>

<ParamField body="metadata" type="object">
  Metadados livres, como o ID do pedido.
</ParamField>

<ParamField body="partner_checkout_url" type="string">
  URL HTTPS opcional do checkout da sua loja.
</ParamField>

<ParamField body="notification_url" type="string" required>
  URL HTTPS pública que recebe eventos.
</ParamField>

<RequestExample>
  ```json theme={null}
  {
    "customer": {
      "email": "cliente@loja.com",
      "name": "Ana Silva",
      "document": "39053344705"
    },
    "amount": 19.9,
    "currency": "BRL",
    "metadata": { "order_id": "1001" },
    "notification_url": "https://loja.com/webhooks/agitapay"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "store": { "id": "uuid-da-loja", "name": "Padrão" },
    "status": "waiting_payment",
    "amount": 19.9,
    "currency": "BRL",
    "qrcode": "data:image/png;base64,...",
    "copy_paste": "000201...",
    "notification_url": "https://loja.com/webhooks/agitapay",
    "paid_at": null
  }
  ```
</ResponseExample>

<ResponseField name="qrcode" type="string">
  Data URI PNG pronta para usar em `<img src="…">`.
</ResponseField>

<ResponseField name="copy_paste" type="string">
  Código PIX EMV copia-e-cola.
</ResponseField>

<ResponseField name="status" type="string">
  `waiting_payment`, `paid`, `expired`, `cancelled` ou `failed`.
</ResponseField>

O valor deve respeitar os limites configurados pela plataforma. Fora da faixa, a API retorna `422 amount_below_minimum` ou `422 amount_above_maximum`.

<Warning>
  Libere produto somente após receber `payment.paid` e confirmar com `GET /payments/{id}`.
</Warning>