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

# Documentação NyxPag

> Como integrar Pix na NyxPag: cobranças com QR Code, transferências, split, saldo, MED e webhooks assinados, tudo numa API REST em português.

A NyxPag é um gateway de Pix. A API existe para você cobrar e pagar sem construir a parte difícil: conexão bancária, conciliação, retentativa de webhook e controle de saldo.

O ciclo é sempre o mesmo, e vale entender antes de escrever qualquer linha:

1. **Você cria a cobrança** com o valor, os dados do pagador e uma chave de idempotência.
2. **A resposta traz o Pix**: um QR Code em base64 e o código Copia e Cola.
3. **O cliente paga.** Você não participa desse passo, e é de propósito: a chave Pix e o app do banco ficam com ele.
4. **A gente avisa.** Um `POST` assinado chega na sua URL, o valor entra no seu saldo e o estado fica disponível por consulta.

A API é REST sobre JSON e autentica com um header. Não existe SDK para instalar: qualquer linguagem que faça uma requisição HTTP integra, e os exemplos daqui vêm em cURL, JavaScript, Python e PHP.

<CardGroup cols={2}>
  <Card title="Sua primeira cobrança" icon="rocket" href="/quickstart">
    Do zero ao QR Code Pix em poucos minutos.
  </Card>

  <Card title="Referência da API" icon="code" href="/api-reference/pagamentos/criar-cobrança-pix">
    Todos os endpoints, parâmetros e respostas.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Como a NyxPag avisa, e como você confere que fomos nós.
  </Card>

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

## O caminho mais curto

Uma cobrança de R\$ 149,90, com um pedido seu como referência:

<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",
      "payer": { "name": "Maria Silva", "document": "52998224725" }
    }'
  ```

  ```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",
      payer: { name: "Maria Silva", document: "52998224725" },
    }),
  });

  const { data } = await res.json();
  console.log(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",
          "payer": {"name": "Maria Silva", "document": "52998224725"},
      },
      timeout=15,
  )
  print(res.json()["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',
          'payer' => ['name' => 'Maria Silva', 'document' => '52998224725'],
      ]),
  ]);
  $body = json_decode(curl_exec($ch), true);
  echo $body['data']['pix']['copyPaste'];
  ```
</CodeGroup>

<Warning>
  Não existe sandbox: os exemplos apontam para produção (`https://api.nyxpag.com.br/v1`) e cobranças criadas são reais. Veja [Ambientes](/guides/comece-aqui/ambientes) para testar com segurança usando valores baixos.
</Warning>

## O que você pode fazer

<CardGroup cols={2}>
  <Card title="Receber por Pix" icon="qr-code" href="/guides/pix/receber">
    Cobranças com QR Code e Copia e Cola, com confirmação por webhook.
  </Card>

  <Card title="Dividir o valor (split)" icon="split" href="/guides/pix/split">
    Repasse parte de cada venda para outras contas NyxPag na hora da aprovação.
  </Card>

  <Card title="Transferir por Pix" icon="send" href="/guides/pix/transferir">
    Envie por chave Pix, Copia e Cola ou QR Code.
  </Card>

  <Card title="Consultar saldo" icon="wallet" href="/guides/pix/saldo">
    Saldo disponível e reservado, em reais.
  </Card>

  <Card title="Acompanhar transações" icon="search" href="/guides/pix/acompanhar">
    Liste, filtre e confira o estado atual de cada operação.
  </Card>

  <Card title="Contestações (MED)" icon="scale" href="/guides/disputas/med">
    Acompanhe contestações Pix e o valor retido até a decisão.
  </Card>

  <Card title="Servidor MCP" icon="bot" href="/guides/mcp">
    Conecte um assistente de IA ao saldo e às transações, somente leitura.
  </Card>

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

## Base URL e convenções

```text theme={"dark"}
https://api.nyxpag.com.br/v1
```

| Convenção | Como é |
| - | - |
| Formato | JSON em requisições e respostas |
| Dinheiro | Reais decimais: `149.90` é R\$ 149,90 |
| Datas | ISO 8601 em UTC |
| Autenticação | `Authorization: Bearer nyx_live_...` |
| Idempotência | `Idempotency-Key` ou `externalId`, obrigatório nas operações financeiras |
| Sucesso | `success: true`, `data` e `requestId` |
| Erro | `success: false`, `error.code`, `error.message` e `requestId` |
| Limite | 100 requisições por 60 segundos, por API Key |

## Endpoints disponíveis

| Endpoint | Permissão | O que faz |
| - | - | - |
| `GET /balance` | `balance:read` | Saldo disponível e reservado |
| `POST /transactions` | `payments:write` | Cria uma cobrança Pix |
| `GET /transactions` | `transactions:read` | Lista transações com filtros e paginação |
| `GET /transactions/{id}` | `transactions:read` | Consulta por ID ou `externalId` |
| `POST /transfers` | `transfers:write` | Envia saldo por Pix |
| `GET /meds` | `transactions:read` | Lista contestações MED |
| `GET /meds/{id}` | `transactions:read` | Consulta uma contestação MED |
| `GET /transparency` | pública | Indicadores consolidados da plataforma |

<Note>
  A API pública da NyxPag cobre **Pix**. Cartão, boleto e outros meios de pagamento não fazem parte da v1.
</Note>

## Precisa de ajuda?

<CardGroup cols={2}>
  <Card title="Dashboard NyxPag" icon="layout-dashboard" href="https://nyxpag.com.br">
    Crie chaves, configure webhooks e acompanhe tudo pelo painel.
  </Card>

  <Card title="Suporte" icon="life-buoy" href="mailto:suporte@nyxpag.com.br">
    Fale com o time. Leve o `requestId` da requisição.
  </Card>
</CardGroup>


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