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

# Sua primeira cobrança Pix

> Crie uma chave, gere uma cobrança Pix, mostre o QR Code ao pagador e confirme o pagamento com a NyxPag API, do zero ao primeiro Pix recebido.

Em poucos minutos você sai do zero e chega a um QR Code Pix funcionando. No fim, você sabe criar, apresentar e confirmar uma cobrança.

<Warning>
  Não existe sandbox. Os exemplos apontam para produção (`https://api.nyxpag.com.br/v1`) e a cobrança é **real**: se você pagar, o dinheiro entra na sua conta. Para testar, use um valor baixo, como R\$ 1,00.
</Warning>

## Antes de começar

<Steps>
  <Step title="Conta NyxPag verificada">
    As rotas financeiras exigem a conta com verificação de identidade concluída. Sem ela, a API responde `403` com `kyc_required`. Crie a conta em [nyxpag.com.br](https://nyxpag.com.br).
  </Step>

  <Step title="Uma API Key com a permissão certa">
    Em [Dashboard → Chaves de API](https://nyxpag.com.br/dashboard/credentials), clique em **Nova chave**, dê um nome e marque **Pagamentos** (`payments:write`) e **Transações** (`transactions:read`). A chave começa com `nyx_live_` e aparece **uma única vez**.
  </Step>

  <Step title="Um servidor para guardar a chave">
    A chave movimenta dinheiro. Ela fica no seu servidor, nunca em frontend, app mobile ou repositório.
  </Step>
</Steps>

## 1. Guarde a chave numa variável de ambiente

```bash theme={"dark"}
export NYXPAG_API_KEY="nyx_live_cole_sua_chave_aqui"
```

## 2. Crie a cobrança

`POST /transactions` cria a cobrança e devolve o QR Code e o Copia e Cola.

Toda cobrança precisa de uma chave de idempotência: o cabeçalho `Idempotency-Key` **ou** o campo `externalId`. Aqui usamos `externalId`, que vem do seu número de pedido. Nas duas formas o valor é salvo como `externalId` da transação, e você consulta depois por ele.

<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": 1.00,
      "externalId": "TESTE-0001",
      "description": "Primeira cobrança",
      "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: 1.0,
      externalId: "TESTE-0001",
      description: "Primeira cobrança",
      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.id, 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": 1.00,
          "externalId": "TESTE-0001",
          "description": "Primeira cobrança",
          "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"]["id"], 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' => 1.00,
          'externalId' => 'TESTE-0001',
          'description' => 'Primeira cobrança',
          'payer' => [
              'name' => 'Maria Silva',
              'document' => '52998224725',
              'email' => 'maria@example.com',
          ],
      ]),
  ]);
  $body = json_decode(curl_exec($ch), true);
  echo $body['data']['id'] . ' ' . $body['data']['pix']['copyPaste'];
  ```
</CodeGroup>

### O que volta (201)

```json theme={"dark"}
{
  "success": true,
  "idempotent": false,
  "data": {
    "id": "txn_mabc123_0123456789abcdef",
    "externalId": "TESTE-0001",
    "direction": "in",
    "type": "payment",
    "method": "pix",
    "status": "pending",
    "expired": false,
    "processingState": "monitoring",
    "amount": 1,
    "fee": 0.5,
    "netAmount": 0.5,
    "description": "Primeira cobrança",
    "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..."
}
```

<Note>
  Os valores de `fee` e `netAmount` são ilustrativos. A tarifa real depende da sua conta e vem sempre na resposta. Todos os campos estão em [Ciclo de vida](/guides/confiabilidade/ciclo-de-vida).
</Note>

### Códigos de resposta

| Código | O que significa | O que fazer |
| - | - | - |
| `201` | Cobrança criada agora | Mostre o Pix ao pagador |
| `200` | Você já tinha criado com essa chave e o mesmo corpo | Use a resposta, é a mesma cobrança |
| `202` | Recebida e em reconciliação automática | **Não é pagamento.** Aguarde o webhook |
| `400` | Dado inválido, como CPF ou valor fora do limite | Corrija e reenvie |
| `409` | Mesma chave com corpo diferente (`idempotency_conflict`) | Veja [Idempotência](/guides/idempotencia) |

<Warning>
  Só considere a cobrança **paga** quando o `status` for `approved`. Um `201` ou `202` apenas diz que a cobrança existe.
</Warning>

## 3. Mostre o Pix ao pagador

Use `data.pix.qrCodeBase64` como imagem e `data.pix.copyPaste` como código Copia e Cola:

```html theme={"dark"}
<img src="data:image/png;base64,{qrCodeBase64}" alt="QR Code Pix" />
<button data-copy="{copyPaste}">Copiar código Pix</button>
```

O Pix vale **15 minutos** (`expiresAt`). Depois disso a NyxPag cancela a cobrança. Mostre um contador para o cliente e ofereça gerar um novo código quando expirar.

## 4. Receba a confirmação

Quando o cliente paga, a NyxPag envia `transaction.approved` para o seu webhook. É o caminho recomendado.

<Card title="Configurar webhooks" icon="webhook" href="/guides/webhooks">
  Registre a URL, valide a assinatura e responda `2xx`.
</Card>

Ainda sem webhook? Consulte pelo seu próprio número de pedido:

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl "https://api.nyxpag.com.br/v1/transactions/TESTE-0001?refresh=true" \
    -H "Authorization: Bearer $NYXPAG_API_KEY"
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch(
    "https://api.nyxpag.com.br/v1/transactions/TESTE-0001?refresh=true",
    { headers: { Authorization: `Bearer ${process.env.NYXPAG_API_KEY}` } },
  );
  const { data } = await res.json();
  console.log(data.status); // pending | approved | failed | cancelled | refunded
  ```

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

  res = requests.get(
      "https://api.nyxpag.com.br/v1/transactions/TESTE-0001",
      params={"refresh": "true"},
      headers={"Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}"},
      timeout=15,
  )
  print(res.json()["data"]["status"])
  ```

  ```php PHP theme={"dark"}
  <?php
  $ch = curl_init('https://api.nyxpag.com.br/v1/transactions/TESTE-0001?refresh=true');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NYXPAG_API_KEY')],
  ]);
  echo json_decode(curl_exec($ch), true)['data']['status'];
  ```
</CodeGroup>

`refresh=true` força a NyxPag a conferir o estado mais recente enquanto a cobrança está `pending`. Use com moderação: cada consulta gasta a cota de 100 requisições por minuto da chave.

<Tip>
  Prefira webhook a consulta repetida. Consultar a cada poucos segundos esgota a cota e ainda é mais lento do que receber o aviso.
</Tip>

## O que fazer com cada estado

| `status` | Significa | Ação |
| - | - | - |
| `pending` | Esperando o pagamento | Mostre o Pix e aguarde |
| `approved` | Pago | Libere o pedido |
| `cancelled` | Cancelada. Se `expired` for `true`, passou de 15 minutos | Gere uma nova cobrança |
| `failed` | Falhou | Avise o cliente e crie uma nova |
| `refunded` | Estornada | Reverta o pedido |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Visão geral da API" icon="layers" href="/guides/api-visao-geral">
    Convenções, formato de resposta e mapa de endpoints.
  </Card>

  <Card title="Autenticação" icon="key-round" href="/guides/autenticacao">
    Permissões, rotação e boas práticas da chave.
  </Card>

  <Card title="Idempotência" icon="repeat" href="/guides/idempotencia">
    Reenvie com segurança sem cobrar duas vezes.
  </Card>

  <Card title="Antes de ir para produção" icon="list-checks" href="/guides/confiabilidade/checklist-producao">
    A lista do que costuma quebrar no primeiro dia.
  </Card>
</CardGroup>


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