Skip to main content
Cada resposta é independente: vá direto ao que precisa.

​
Começando

Não. A NyxPag tem um único ambiente, o de produção, e toda API Key opera nele. Para testar, use valores baixos (a partir de R$ 1,00) e pague pelo seu banco. Dá para testar o seu receptor de webhook sem gastar nada, assinando um evento localmente. Veja Ambientes.
Em Dashboard → Chaves de API. A conta precisa ter a verificação de identidade concluída para usar a API. A chave aparece uma única vez. Veja Gestão de chaves.
Não. A chave movimenta dinheiro e não pode sair do servidor. Faça o seu frontend chamar o seu backend, e o backend chamar a NyxPag. A única exceção é GET /transparency, que é público.
Não existe SDK oficial. A API é REST sobre JSON, e qualquer linguagem com cliente HTTP integra. A documentação traz exemplos em cURL, JavaScript, Python e PHP, e a especificação OpenAPI 3.1 em https://api.nyxpag.com.br/v1/openapi.json permite gerar um cliente.
Somente BRL. Os valores são reais decimais: 10.50 é R$ 10,50.

​
Cobranças

15 minutos a partir da criação. O prazo está em expiresAt. Se ninguém pagar, a cobrança vira cancelled com expired: true e o webhook transaction.cancelled é enviado.
O campo payer.document valida CPF. Para uma venda a uma empresa, informe o CPF do responsável pelo pagamento.
Não há endpoint de cancelamento. A cobrança expira sozinha em 15 minutos. Enquanto isso, ela continua válida: se o cliente pagar, o valor entra.
Não. A API pública não tem endpoint de reembolso. O estado refunded existe, mas não é acionado por uma chamada sua e não dispara webhook.
Não. A API pública da NyxPag cobre Pix: cobrança, transferência, consulta, saldo e MED.
Numa cobrança, é o valor que o pagador paga. Com coverFee: false é igual ao que você enviou. Com coverFee: true é maior, porque inclui a tarifa. Veja Receber por Pix.
Depende da configuração da sua conta e vem sempre no campo fee da resposta. Os valores que aparecem na documentação são exemplos.
Com o campo split na criação da cobrança, por valor fixo ou por percentual, para até 10 contas NyxPag. Veja Split.

​
Idempotência e respostas

Nenhuma na prática: são duas formas de mandar a mesma chave, e o valor vira o externalId da transação. Use o cabeçalho ou o campo. Se mandar os dois, os valores precisam ser iguais, senão é 409. Veja Idempotência.
Trate como pendente. A operação foi recebida e está em reconciliação automática. Aguarde o webhook com o resultado, ou consulte GET /transactions/{id}. Nunca libere o pedido por causa de um 202.
201 criou agora. 200 é uma repetição idempotente: a operação já existia. Os dois trazem os dados da operação, e idempotent: true indica a repetição.
A chave não expira e continua apontando para a operação original. Para gerar um novo Pix para o mesmo pedido, use uma chave nova, como PEDIDO-1042-t2. Veja Idempotência.

​
Transferências

R$ 3,00, conforme a especificação OpenAPI atual.
Não. Só pode haver uma transferência pending por conta. A seguinte recebe 409 (WITHDRAWAL_IN_PROGRESS) até a anterior terminar. Enfileire do seu lado. Veja Transferir por Pix.
Só se o código for estático e sem valor. Se o código já define o valor, omita amount: o valor do código prevalece.
Não. A NyxPag escolhe a rota de processamento da conta. O cliente da API não escolhe nem troca.

​
Webhooks

localhost é recusado, então use um túnel HTTPS (ngrok, cloudflared) e cadastre a URL gerada. Para testar sem pagar nada, assine um evento com um segredo seu e envie para o seu servidor. Veja Ambientes.
O segredo de assinatura do webhook, mostrado uma única vez ao criar o endpoint em Dashboard → Webhooks. Veja Validando a assinatura.
Até 8 tentativas, com espera crescente a partir de cerca de 30 segundos e teto de 1 hora. Depois disso a entrega é marcada como falha e não é repetida. Concilie por GET /transactions. Veja Webhooks.
Não: a entrega é ao menos uma vez. Deduplique pelo id do evento (transaction.*) ou pelo cabeçalho X-NyxPag-Delivery (med.*).

​
Limites e MED

100 por janela de 60 segundos, por API Key, somando todas as rotas e o MCP. Os cabeçalhos RateLimit-* mostram o estado, e Retry-After diz quanto esperar no 429. Veja Limites.
É a contestação de um Pix pelo pagador. Enquanto ela é analisada, o valor fica retido. Na API é somente leitura. Veja Contestações (MED).
Sim, pelo servidor MCP, que é somente leitura: saldo e transações, sem CPF, e-mail ou Copia e Cola.

Troubleshooting

Sintomas comuns e como resolver.

Glossário

Os termos da API explicados.