Roteiro de integração com a NyxPag

O 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

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.

Tudo acontece em produção e com dinheiro real. Siga o roteiro com valores baixos. Veja Ambientes.

O roteiro

Crie a chave com permissões mínimas

Em Dashboard → Chaves de API, crie uma chave para o checkout com payments:write, transactions:read e balance:read. Deixe transfers:write de fora. Veja Gestão de chaves.

Guarde a chave num cofre

Variável de ambiente ou gerenciador de segredos. Nunca no código.

export NYXPAG_API_KEY="nyx_live_cole_sua_chave_aqui"

Valide a chave com GET /balance

É a chamada mais barata para confirmar que a autenticação funciona.

curl https://api.nyxpag.com.br/v1/balance \
  -H "Authorization: Bearer $NYXPAG_API_KEY"

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

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

Resposta esperada:

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

Cadastre o endpoint de webhook

Em Dashboard → Webhooks, informe a URL HTTPS do seu servidor, vincule à chave e guarde o segredo de assinatura. Veja Webhooks.

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.

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.

{
  "amount": 1.00,
  "externalId": "teste-validacao-001",
  "description": "Validação de integração",
  "payer": { "name": "Seu Nome Completo", "document": "SEU_CPF", "email": "[email protected]" }
}

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

Pague pelo seu banco

Escaneie o QR Code ou cole o Copia e Cola no app do seu banco.

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.

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.

Revise o checklist e vá para produção

Siga Antes de ir para produção, troque a chave de teste pela de produção e libere.

Se algo não funcionar

Sintoma	Veja
`401` ou `403`	Autenticação
`400` na criação	Erros
Webhook não chega	Webhooks e Troubleshooting
Assinatura não bate	Validando a assinatura
Pix aprovado mas pedido não liberou	Seu receptor: confira deduplicação e persistência

Receber por Pix

Todos os campos e opções da cobrança.

Idempotência

A regra mais importante de uma integração financeira.

Comece aqui

Receber

Dinheiro na conta

Disputas

Confiabilidade

Ajuda

Roteiro de integração com a NyxPag

Como as peças se encaixam

Antes de começar

O roteiro

Se algo não funcionar

Receber por Pix

Idempotência

​Como as peças se encaixam

​Antes de começar

​O roteiro

​Se algo não funcionar

Receber por Pix

Idempotência

Como as peças se encaixam

Antes de começar

O roteiro

Se algo não funcionar