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

# Receber por Pix

> Crie cobranças Pix, mostre o QR Code e o Copia e Cola, entenda coverFee e confirme o pagamento por webhook com a NyxPag API.

`POST /transactions` cria uma cobrança Pix. A resposta traz o QR Code em base64 e o código Copia e Cola, e você mostra os dois ao pagador. Quando ele paga, a NyxPag avisa por webhook.

<Warning>
  A cobrança é real e em produção. Não existe sandbox. Veja [Ambientes](/guides/comece-aqui/ambientes) para testar com segurança.
</Warning>

## O que enviar

| Campo | Obrigatório | Descrição |
| - | - | - |
| `amount` | Sim | Valor em reais, de `1` a `10000`. Ex.: `149.90` |
| `payer.name` | Sim | Nome completo do pagador, com no mínimo 3 caracteres |
| `payer.document` | Sim | **CPF** válido do pagador. Aceita com ou sem pontuação |
| `Idempotency-Key` **ou** `externalId` | Sim | Chave de idempotência, até 100 caracteres. Veja [Idempotência](/guides/idempotencia) |
| `payer.email` | Não | E-mail do pagador |
| `description` | Não | Descrição, até 140 caracteres |
| `coverFee` | Não | Se `true`, o pagador cobre a tarifa. Padrão `false`. Veja [coverFee](#coverfee) |
| `split` | Não | Recebedores da venda, até 10. Veja [Split](/guides/pix/split) |
| `webhookUrl` | Não | URL HTTPS que recebe os eventos desta cobrança |

<Note>
  Hoje o pagador precisa ser pessoa física: o campo `payer.document` valida **CPF**. Para uma venda a uma empresa, informe o CPF do responsável.
</Note>

## Criar a cobrança

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.nyxpag.com.br/v1/transactions \
    -H "Authorization: Bearer $NYXPAG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 149.90,
      "externalId": "PEDIDO-1042",
      "description": "Pedido #1042",
      "webhookUrl": "https://seusite.com.br/webhooks/nyxpag",
      "payer": {
        "name": "Maria Silva",
        "document": "52998224725",
        "email": "maria@example.com"
      }
    }'
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch("https://api.nyxpag.com.br/v1/transactions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NYXPAG_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 149.9,
      externalId: "PEDIDO-1042",
      description: "Pedido #1042",
      webhookUrl: "https://seusite.com.br/webhooks/nyxpag",
      payer: {
        name: "Maria Silva",
        document: "52998224725",
        email: "maria@example.com",
      },
    }),
  });

  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
  console.log(body.data.pix.copyPaste);
  ```

  ```python Python theme={"dark"}
  import os
  import requests

  res = requests.post(
      "https://api.nyxpag.com.br/v1/transactions",
      headers={"Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}"},
      json={
          "amount": 149.90,
          "externalId": "PEDIDO-1042",
          "description": "Pedido #1042",
          "webhookUrl": "https://seusite.com.br/webhooks/nyxpag",
          "payer": {
              "name": "Maria Silva",
              "document": "52998224725",
              "email": "maria@example.com",
          },
      },
      timeout=15,
  )
  body = res.json()
  if not res.ok:
      raise RuntimeError(f"{res.status_code} {body['error']['code']}: {body['error']['message']}")
  print(body["data"]["pix"]["copyPaste"])
  ```

  ```php PHP theme={"dark"}
  <?php
  $ch = curl_init('https://api.nyxpag.com.br/v1/transactions');
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer ' . getenv('NYXPAG_API_KEY'),
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'amount' => 149.90,
          'externalId' => 'PEDIDO-1042',
          'description' => 'Pedido #1042',
          'webhookUrl' => 'https://seusite.com.br/webhooks/nyxpag',
          'payer' => [
              'name' => 'Maria Silva',
              'document' => '52998224725',
              'email' => 'maria@example.com',
          ],
      ]),
  ]);
  $body = json_decode(curl_exec($ch), true);
  echo $body['data']['pix']['copyPaste'];
  ```
</CodeGroup>

## A resposta

```json 201 Created theme={"dark"}
{
  "success": true,
  "idempotent": false,
  "data": {
    "id": "txn_mabc123_0123456789abcdef",
    "externalId": "PEDIDO-1042",
    "direction": "in",
    "type": "payment",
    "method": "pix",
    "status": "pending",
    "expired": false,
    "processingState": "monitoring",
    "amount": 149.9,
    "fee": 0.5,
    "netAmount": 149.4,
    "description": "Pedido #1042",
    "splitAmount": 0,
    "split": [],
    "pix": {
      "copyPaste": "00020126...6304ABCD",
      "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "expiresAt": "2026-10-03T14:15:00.000Z",
    "approvedAt": null,
    "createdAt": "2026-10-03T14:00:00.000Z",
    "updatedAt": "2026-10-03T14:00:00.000Z"
  },
  "requestId": "req_01H..."
}
```

Os valores de `fee` e `netAmount` são ilustrativos: a tarifa real depende da sua conta. Todos os campos estão descritos em [Ciclo de vida](/guides/confiabilidade/ciclo-de-vida).

### Códigos de resposta

| Código | Significado | Ação |
| - | - | - |
| `201` | Cobrança criada agora | Mostre o Pix |
| `200` | Repetição idempotente: a cobrança já existia | Use a resposta |
| `202` | Em reconciliação automática | **Não é pagamento.** Aguarde o webhook |
| `400` | Dado inválido | Corrija. Veja a tabela de erros abaixo |
| `409` | `idempotency_conflict` | Mesma chave, corpo diferente |
| `422` | `operation_refused` | A conta não pode receber Pix agora |

<Warning>
  `202` quer dizer que a cobrança foi recebida e está sendo conferida. Nunca libere um pedido por causa de `201` ou `202`. Só libere com `status: "approved"`.
</Warning>

## Mostrar o Pix ao pagador

```html theme={"dark"}
<img src="data:image/png;base64,{qrCodeBase64}" alt="QR Code Pix" />

<code id="pix">{copyPaste}</code>
<button onclick="navigator.clipboard.writeText(document.getElementById('pix').textContent)">
  Copiar código Pix
</button>
```

* `qrCodeBase64` vem **sem** o prefixo `data:image`. Monte o `src` como acima.
* Use o `copyPaste` **exatamente** como veio. Qualquer espaço ou quebra de linha invalida o código.
* A cobrança vale **15 minutos** (`expiresAt`). Passado esse prazo ela é cancelada, e você recebe `transaction.cancelled` com `expired: true`. Mostre uma contagem regressiva e ofereça gerar um novo Pix.

## Confirmar o pagamento

<Steps>
  <Step title="Pelo webhook (recomendado)">
    A NyxPag envia `transaction.approved` assim que o Pix é pago. Veja [transaction.\*](/webhooks/transacoes).
  </Step>

  <Step title="Pela consulta (fallback)">
    `GET /transactions/{id}?refresh=true` com o `id` ou o seu `externalId`. Use com moderação, porque gasta a cota de 100 requisições por minuto.
  </Step>
</Steps>

```bash theme={"dark"}
curl "https://api.nyxpag.com.br/v1/transactions/PEDIDO-1042?refresh=true" \
  -H "Authorization: Bearer $NYXPAG_API_KEY"
```

## coverFee

`coverFee` decide **quem paga a tarifa** da NyxPag.

| `coverFee` | O pagador paga | Você recebe |
| - | - | - |
| `false` (padrão) | `149.90` | `149.90` menos a tarifa |
| `true` | `149.90` mais a tarifa | `149.90` |

Exemplo com tarifa ilustrativa de R\$ 0,50 e sem split: com `false` o pagador paga R\$ 149,90 e você recebe R\$ 149,40. Com `true` o pagador paga R\$ 150,40 e você recebe R\$ 149,90.

<Warning>
  O campo `amount` **da resposta** é o valor que o **pagador paga**, e não o que você enviou. Com `coverFee: true` ele vem maior (no exemplo, `150.4`). Mostre ao cliente o valor da resposta e guarde o `amount` enviado no seu pedido.
</Warning>

<Note>
  Se você combina `coverFee: true` com [split](/guides/pix/split), crie uma cobrança de R\$ 1,00 e confira `amount`, `fee`, `splitAmount` e `netAmount` na resposta antes de usar em produção.
</Note>

## Erros comuns

| HTTP | `error.code` | Mensagem | O que fazer |
| - | - | - | - |
| `400` | `invalid_request` | Informe o nome completo do pagador | `payer.name` com ao menos 3 caracteres |
| `400` | `invalid_request` | Informe um CPF válido para o pagador | Use um CPF válido |
| `400` | `invalid_request` | O valor informado está fora dos limites configurados para Pix | Valor entre R\$ 1,00 e R\$ 10.000,00 |
| `400` | `invalid_request` | O valor precisa ser maior que a taxa da operação | Aumente o `amount` |
| `400` | `idempotency_key_required` | Envie Idempotency-Key (ou externalId) | Sempre envie uma das duas |
| `400` | `invalid_idempotency_key` | Idempotency-Key deve ter até 100 caracteres | Use letras, números e `. _ : / -` |
| `409` | `idempotency_conflict` | A chave já foi usada com parâmetros diferentes | Veja [Idempotência](/guides/idempotencia) |
| `422` | `operation_refused` | Os recebimentos via Pix estão desabilitados | Fale com o suporte |

<CardGroup cols={2}>
  <Card title="Dividir o valor (split)" icon="split" href="/guides/pix/split">
    Repasse parte da venda a outras contas NyxPag.
  </Card>

  <Card title="Criar cobrança Pix" icon="code" href="/api-reference/pagamentos/criar-cobrança-pix">
    Referência completa do endpoint.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.