Sua primeira cobrança Pix

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.

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.

Antes de começar

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.

Uma API Key com a permissão certa

Em Dashboard → Chaves de API, 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.

Um servidor para guardar a chave

A chave movimenta dinheiro. Ela fica no seu servidor, nunca em frontend, app mobile ou repositório.

1. Guarde a chave numa variável de ambiente

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.

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": "[email protected]"
    }
  }'

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: "[email protected]",
    },
  }),
});

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);

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": "[email protected]",
        },
    },
    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
$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' => '[email protected]',
        ],
    ]),
]);
$body = json_decode(curl_exec($ch), true);
echo $body['data']['id'] . ' ' . $body['data']['pix']['copyPaste'];

O que volta (201)

{
  "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..."
}

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.

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

Só considere a cobrança paga quando o status for approved. Um 201 ou 202 apenas diz que a cobrança existe.

3. Mostre o Pix ao pagador

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

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

Configurar webhooks

Registre a URL, valide a assinatura e responda 2xx.

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

curl "https://api.nyxpag.com.br/v1/transactions/TESTE-0001?refresh=true" \
  -H "Authorization: Bearer $NYXPAG_API_KEY"

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

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
$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'];

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.

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

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

Visão geral da API

Convenções, formato de resposta e mapa de endpoints.

Autenticação

Permissões, rotação e boas práticas da chave.

Idempotência

Reenvie com segurança sem cobrar duas vezes.

Antes de ir para produção

A lista do que costuma quebrar no primeiro dia.

Comece aqui

Receber

Dinheiro na conta

Disputas

Confiabilidade

Ajuda

Sua primeira cobrança Pix

Antes de começar

1. Guarde a chave numa variável de ambiente

2. Crie a cobrança

O que volta (201)

Códigos de resposta

3. Mostre o Pix ao pagador

4. Receba a confirmação

Configurar webhooks

O que fazer com cada estado

Próximos passos

Visão geral da API

Autenticação

Idempotência

Antes de ir para produção

​Antes de começar

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

​2. Crie a cobrança

​O que volta (201)

​Códigos de resposta

​3. Mostre o Pix ao pagador

​4. Receba a confirmação

Configurar webhooks

​O que fazer com cada estado

​Próximos passos

Visão geral da API

Autenticação

Idempotência

Antes de ir para produção

Antes de começar

1. Guarde a chave numa variável de ambiente

2. Crie a cobrança

O que volta (201)

Códigos de resposta

3. Mostre o Pix ao pagador

4. Receba a confirmação

O que fazer com cada estado

Próximos passos