Visão geral da NyxPag API

Uma API REST sobre JSON, um formato de resposta e uma forma de autenticar. Esta página junta o que vale para todos os endpoints, para você não precisar redescobrir em cada um. Base URL: https://api.nyxpag.com.br/v1 Toda requisição autenticada leva o header:

Authorization: Bearer nyx_live_sua_chave

A API se descreve sozinha. GET /v1 devolve o resumo dos endpoints, GET /v1/openapi.json entrega a especificação OpenAPI 3.1 e GET /v1/llms.txt traz um resumo em texto para agentes de IA. Nenhum deles exige autenticação.

Convenções

Dinheiro vai em reais, com casas decimais

149.90 é R$ 149,90. Não há valores em centavos inteiros na API pública: amount, fee, netAmount, available e reserved são sempre reais decimais.

{ "amount": 149.9, "fee": 0.5, "netAmount": 149.4 }

A única moeda é BRL.

O formato de sucesso

Toda resposta de sucesso tem success: true, os dados em data e um requestId:

{
  "success": true,
  "data": { },
  "requestId": "req_01H..."
}

Em criações (POST) há também idempotent (true quando é uma repetição) e, às vezes, warning.

Erro tem sempre a mesma forma

{
  "success": false,
  "error": { "code": "invalid_request", "message": "Texto em português" },
  "requestId": "req_01H..."
}

Decida pelo error.code, que é estável, e não pela message, que pode mudar. Todos os códigos estão em Erros.

requestId: o número do protocolo

Toda resposta, de sucesso ou erro, traz um requestId. Guarde nos seus logs: é o que o suporte pede para achar a requisição.

O prefixo do ID diz o que é

Prefixo	Recurso
`txn_`	Cobrança Pix
`out_`	Transferência Pix
`med_`	Contestação MED
`evt_`	Evento de webhook de transação
`nyx_live_`	API Key

Paginação

As listagens aceitam page (a partir de 1) e limit (de 1 a 100, padrão 20) e devolvem pagination:

{ "pagination": { "page": 1, "limit": 20, "total": 42, "pages": 3 } }

Vale para GET /transactions e GET /meds.

Datas

Sempre ISO 8601 em UTC, por exemplo 2026-10-03T14:00:00.000Z. Converta para o fuso do usuário na sua tela.

Idempotência nas operações financeiras

POST /transactions e POST /transfers exigem Idempotency-Key (cabeçalho) ou externalId (corpo). Repetir a mesma chave com o mesmo corpo devolve a operação original, sem duplicar. Veja Idempotência.

Versão da API

Toda resposta traz o cabeçalho X-NyxPag-Version. A versão atual da v1 é 1.1.0. Mudanças relevantes ficam no Changelog.

Códigos de resposta

Código	Quando
`200`	Consulta ok, ou repetição idempotente de uma criação
`201`	Cobrança ou transferência criada agora
`202`	Operação recebida e em reconciliação. Não é confirmação
`400`	Dados inválidos
`401`	API Key ausente, inválida ou revogada
`403`	Sem permissão, IP não autorizado ou conta sem verificação
`404`	Não encontrado
`409`	Conflito de idempotência
`422`	Operação recusada por regra de negócio
`429`	Passou de 100 requisições por 60 segundos
`5xx`	Erro do nosso lado. Tente de novo com a mesma chave de idempotência

O mapa

Grupo	Endpoint	Permissão	Guia
Saldo	`GET /balance`	`balance:read`	Saldo
Pagamentos	`POST /transactions`	`payments:write`	Receber por Pix
Transações	`GET /transactions`	`transactions:read`	Acompanhar
Transações	`GET /transactions/{id}`	`transactions:read`	Acompanhar
Transferências	`POST /transfers`	`transfers:write`	Transferir por Pix
MED	`GET /meds`	`transactions:read`	Contestações
MED	`GET /meds/{id}`	`transactions:read`	Contestações
Transparência	`GET /transparency`	pública	Transparência

Limites que valem lembrar

O quê	Limite
Requisições	100 por janela de 60 segundos, por API Key, somando todas as rotas e o MCP
Valor de uma cobrança	De R$ 1,00 a R$ 10.000,00
Valor mínimo de transferência	R$ 3,00
Chave de idempotência	Até 100 caracteres: letras, números e `. _ : / -`
Descrição	Até 140 caracteres
Recebedores de split	Até 10 por venda
Validade do Pix	15 minutos

Os valores mínimos e máximos refletem a especificação OpenAPI atual e podem ser ajustados pela NyxPag por conta. A fonte de verdade é sempre /v1/openapi.json.

Autenticação

Como enviar a chave, permissões e boas práticas.

Referência da API

Cada endpoint com parâmetros, respostas e exemplos.

Comece aqui

Receber

Dinheiro na conta

Disputas

Confiabilidade

Ajuda

Visão geral da NyxPag API

Convenções

Códigos de resposta

O mapa

Limites que valem lembrar

Autenticação

Referência da API

​Convenções

​Códigos de resposta

​O mapa

​Limites que valem lembrar

Autenticação

Referência da API

Convenções

Códigos de resposta

O mapa

Limites que valem lembrar