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

# Roteiro de integração com a NyxPag

> O passo a passo completo para integrar Pix em produção: chave, webhook, primeira cobrança, validação do fluxo e preparação antes de escalar.

O [Quickstart](/quickstart) mostra a primeira cobrança. Este roteiro vai além: leva a integração inteira do zero até estar pronta para receber dinheiro de verdade, com a ordem certa das coisas e o que conferir em cada etapa.

## Como as peças se encaixam

```mermaid theme={"dark"}
sequenceDiagram
    participant C as Cliente
    participant S as Seu servidor
    participant N as NyxPag
    participant B as Banco do cliente

    C->>S: Finaliza o pedido
    S->>N: POST /transactions (externalId)
    N-->>S: 201 com QR Code e Copia e Cola
    S-->>C: Mostra o Pix
    C->>B: Paga o Pix
    B->>N: Confirma o pagamento
    N->>S: POST webhook transaction.approved
    S-->>N: 200 OK
    S-->>C: Libera o pedido
```

Duas regras sustentam tudo: **a chave nunca sai do seu servidor**, e **só o webhook (ou uma consulta) diz que o Pix foi pago**. A resposta de criação nunca é prova de pagamento.

## Antes de começar

* Conta NyxPag com a **verificação de identidade concluída**.
* Um servidor com URL pública em **HTTPS**, para receber webhooks.
* Um lugar seguro para guardar segredos.
* Um banco de dados seu, para guardar o pedido, a chave de idempotência e os eventos já processados.

<Warning>
  Tudo acontece em produção e com dinheiro real. Siga o roteiro com valores baixos. Veja [Ambientes](/guides/comece-aqui/ambientes).
</Warning>

## O roteiro

<Steps>
  <Step title="Crie a chave com permissões mínimas">
    Em [Dashboard → Chaves de API](https://nyxpag.com.br/dashboard/credentials), crie uma chave para o checkout com `payments:write`, `transactions:read` e `balance:read`. Deixe `transfers:write` de fora. Veja [Gestão de chaves](/guides/comece-aqui/api-key).
  </Step>

  <Step title="Guarde a chave num cofre">
    Variável de ambiente ou gerenciador de segredos. Nunca no código.

    ```bash theme={"dark"}
    export NYXPAG_API_KEY="nyx_live_cole_sua_chave_aqui"
    ```
  </Step>

  <Step title="Valide a chave com GET /balance">
    É a chamada mais barata para confirmar que a autenticação funciona.

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

      ```javascript JavaScript theme={"dark"}
      const res = await fetch("https://api.nyxpag.com.br/v1/balance", {
        headers: { Authorization: `Bearer ${process.env.NYXPAG_API_KEY}` },
      });
      console.log(await res.json());
      ```

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

      res = requests.get(
          "https://api.nyxpag.com.br/v1/balance",
          headers={"Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}"},
          timeout=15,
      )
      print(res.json())
      ```

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

    Resposta esperada:

    ```json theme={"dark"}
    {
      "success": true,
      "data": { "currency": "BRL", "available": 0, "reserved": 0 },
      "requestId": "req_01H..."
    }
    ```

    Recebeu `401`? Confira o cabeçalho e o prefixo. Recebeu `403`? Leia o `error.code` em [Autenticação](/guides/autenticacao).
  </Step>

  <Step title="Cadastre o endpoint de webhook">
    Em [Dashboard → Webhooks](https://nyxpag.com.br/dashboard/webhooks), informe a URL HTTPS do seu servidor, vincule à chave e **guarde o segredo de assinatura**. Veja [Webhooks](/guides/webhooks).
  </Step>

  <Step title="Implemente o receptor antes de cobrar">
    Valide a assinatura, deduplique, persista e responda `2xx`. Teste localmente com um evento assinado por você, sem gastar nada. Veja [Ambientes](/guides/comece-aqui/ambientes).
  </Step>

  <Step title="Crie uma cobrança de R$ 1,00">
    Use um `externalId` com prefixo de teste. Guarde esse `externalId` no seu banco **antes** de chamar a API.

    ```json theme={"dark"}
    {
      "amount": 1.00,
      "externalId": "teste-validacao-001",
      "description": "Validação de integração",
      "payer": { "name": "Seu Nome Completo", "document": "SEU_CPF", "email": "voce@seudominio.com.br" }
    }
    ```

    <Tip>
      Prefixe os testes (`teste-`) para identificá-los no extrato e evitar colisão de idempotência com pedidos reais.
    </Tip>
  </Step>

  <Step title="Pague pelo seu banco">
    Escaneie o QR Code ou cole o Copia e Cola no app do seu banco.
  </Step>

  <Step title="Confira que o webhook chegou">
    O seu receptor deve receber `transaction.approved` com `data.externalId` igual ao do passo 6 e `data.status: "approved"`. Se não chegou, veja [Troubleshooting](/guides/ajuda/troubleshooting).
  </Step>

  <Step title="Teste os caminhos ruins">
    Reenvie a mesma criação com a mesma chave (deve voltar `200`, sem duplicar). Mude o valor com a mesma chave (deve voltar `409`). Crie e **não** pague, e espere 15 minutos pelo `cancelled`.
  </Step>

  <Step title="Revise o checklist e vá para produção">
    Siga [Antes de ir para produção](/guides/confiabilidade/checklist-producao), troque a chave de teste pela de produção e libere.
  </Step>
</Steps>

## Se algo não funcionar

| Sintoma | Veja |
| - | - |
| `401` ou `403` | [Autenticação](/guides/autenticacao) |
| `400` na criação | [Erros](/guides/erros) |
| Webhook não chega | [Webhooks](/guides/webhooks) e [Troubleshooting](/guides/ajuda/troubleshooting) |
| Assinatura não bate | [Validando a assinatura](/webhooks/assinatura) |
| Pix aprovado mas pedido não liberou | Seu receptor: confira deduplicação e persistência |

<CardGroup cols={2}>
  <Card title="Receber por Pix" icon="qr-code" href="/guides/pix/receber">
    Todos os campos e opções da cobrança.
  </Card>

  <Card title="Idempotência" icon="repeat" href="/guides/idempotencia">
    A regra mais importante de uma integração financeira.
  </Card>
</CardGroup>


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