Changelog da NyxPag API

Este changelog registra mudanças relevantes na API pública da NyxPag e na documentação. A versão atual da API é 1.1.0, informada em todas as respostas no cabeçalho X-NyxPag-Version.

​

2026-10-03

​

Documentação reescrita

A documentação foi reorganizada e revisada contra o comportamento real da API. Novas páginas

• Dividir o valor (split): o campo split de POST /transactions, com limites e erros.
• Contestações (MED): GET /meds, GET /meds/{id} e como tratar cada status.
• Visão geral da API: convenções, formato de resposta, paginação e mapa de endpoints.
• Aba Webhooks, com assinatura, transaction.* e med.*.

Correções importantes para quem já integrou

• Chave da assinatura do webhook. A chave é o segredo do webhook, mostrado ao criar o endpoint em Dashboard → Webhooks. Antes a documentação descrevia apenas o caso legado, em que a chave é o SHA-256 da API Key em hexadecimal, usado por chaves sem endpoint configurado. Veja Validando a assinatura.
• Códigos de erro. O 401 é invalid_api_key (não unauthorized). O 403 pode ser permission_denied, ip_not_allowed, kyc_required ou account_unavailable. O 422 é operation_refused. Veja Erros.
• Valores em reais. A API devolve reais decimais em todos os campos. Exemplos antigos que mostravam centavos foram corrigidos.
• Pagador. payer.document valida CPF.
• Valor mínimo de transferência. R$ 3,00.
• amount da resposta. Numa cobrança é o valor que o pagador paga, e é maior que o enviado com coverFee: true.
• Um saque por vez. Só pode haver uma transferência pending por conta (WITHDRAWAL_IN_PROGRESS).
• Corpo do 429. O formato é o descrito em Erros, com retryAfter.

​

Esclarecido

• Não existe sandbox: toda chave opera em produção.
• Não há endpoint de cancelamento ou de reembolso. Cobranças expiram em 15 minutos.
• A idempotência vale enquanto a transação existir. Para refazer uma operação encerrada, use uma chave nova.
• Webhook: até 8 tentativas, timeout de 8 segundos, sem seguir redirecionamentos.

​

2026-08-26

​

Adicionado

• Campo destination em POST /transfers, com suporte a três tipos: pix_key, pix_copy_paste e qr_code. É a alternativa moderna ao formato legado com pixKey e pixKeyType, que segue funcionando.
• Guia de ciclo de vida das transações e checklist de produção.

​

Corrigido

• O contrato do webhook passou a refletir os cabeçalhos X-NyxPag-Signature (formato t=<ts>,v1=<hex>), X-NyxPag-Event e X-NyxPag-Delivery.
• O Quickstart passou a usar externalId ou Idempotency-Key, nunca os dois com valores diferentes.
• O código de erro do status 429 foi corrigido para rate_limit_exceeded.

​

Documentado

• Rate limit de 100 requisições por janela de 60 segundos por API Key, compartilhado com o MCP. Cabeçalhos de resposta: Retry-After, RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset.
• Redirects das URLs antigas sem acento em /api-reference.