Skip to main content
Procure o sintoma, siga os passos na ordem. A maioria dos problemas se resolve lendo o error.code da resposta, então comece sempre por ele.

​
Antes de abrir um chamado

1

Guarde o requestId

Toda resposta, de sucesso ou erro, traz requestId. É o protocolo da requisição.
2

Reproduza com cURL

Isola o problema do seu código e do seu cliente HTTP.
3

Envie ao suporte

Mande o requestId, o cURL sem a sua chave, o horário com fuso e o que você esperava, para [email protected].

​
Autenticação

A chave está ausente, mal formada, não existe ou foi revogada.
1

Confira o cabeçalho

Precisa ser Authorization: Bearer nyx_live_..., com a palavra Bearer e um espaço.
2

Confira a chave

Sem espaço ou quebra de linha no final, ao copiar. Ela começa com nyx_.
3

Confira no dashboard

Em Chaves de API, veja se ela segue ativa. Uma chave renovada invalida a anterior na hora.
A chave é válida, mas não tem a permissão do endpoint. A message diz qual: Permissão necessária: payments:write.Crie uma nova chave com a permissão. Veja Gestão de chaves.
A chave está restrita a IPs e a requisição saiu de outro. Chame a partir do IP autorizado, ou peça ao suporte para atualizar a lista. Em ambiente serverless, o IP de saída muda: use um NAT com IP fixo.
A conta ainda não concluiu a verificação de identidade. Conclua no dashboard.
A conta está bloqueada ou indisponível. Fale com o suporte.

​
Cobranças

Leia a message. Os motivos mais comuns:
É o esperado: 201 só diz que a cobrança existe. O pagamento chega depois, em transaction.approved. Libere o pedido apenas com status: "approved".
O dinheiro entrou, então o problema está no seu receptor de webhook.
1

Consulte a transação

GET /transactions/{externalId}. Se vier approved, o pagamento está certo e o seu webhook falhou.
2

Veja se o webhook chegou

Confira os logs do seu servidor na hora do pagamento. Se não chegou, veja Webhook não chega.
3

Veja se a assinatura foi rejeitada

Um receptor que valida errado descarta o evento válido. Veja Assinatura inválida.
4

Rode a conciliação

Um job que lista as transações approved recentes resolve pedidos presos. Veja Acompanhar.
qrCodeBase64 vem sem o prefixo data:image. Monte o src assim:
Use o texto exatamente como veio em pix.copyPaste. Espaço, quebra de linha ou truncamento invalida o código.
A chave de idempotência não expira e aponta para a operação original. Para refazer depois de a cobrança terminar, use uma chave nova (PEDIDO-1042-t2). Veja Idempotência.
Você usou coverFee: true. O amount da resposta é o que o pagador paga e inclui a tarifa. Veja coverFee.

​
Transferências

Já existe uma transferência pending na conta. Só pode haver uma por vez. Espere transaction.approved ou failed da anterior e envie a próxima. Enfileire do seu lado.
O disponível não cobre o valor mais a tarifa. Confira com GET /balance. Lembre que coverFee: true (o padrão) soma a tarifa ao que sai do saldo.
A administração bloqueou temporariamente os saques da conta. Fale com o suporte.
O código é estático e sem valor. Envie amount. Quando o código já tem valor, omita amount.
Em pix_key, envie destination.value e destination.keyType (cpf, cnpj, email, phone ou random), e confira que o tipo bate com o formato da chave.
Pode demorar. 202 e pending com processingState: "reconciling" significam que a NyxPag está conferindo o resultado. Aguarde o webhook. Não envie de novo: reenviar com outra chave cria um segundo envio.

​
Webhook

1

A URL é aceitável?

HTTPS, porta 443, sem usuário e senha, sem #, e que não resolva para rede privada nem localhost. Veja as regras.
2

A URL redireciona?

Redirecionamentos não são seguidos e contam como falha. Cadastre a URL final.
3

O endpoint responde 2xx em até 8 segundos?

Qualquer outra resposta, ou demora, conta como falha e agenda nova tentativa.
4

Há endpoint vinculado à chave?

Em Dashboard → Webhooks, confira se há um endpoint para a chave que criou a operação. Ou envie webhookUrl na requisição.
5

Já esgotou as tentativas?

Depois de 8 falhas a NyxPag não tenta mais. Recupere pelo GET /transactions.
Em ordem de probabilidade:
1

Corpo reserializado

Valide sobre o corpo bruto. Fazer JSON.parse e JSON.stringify muda a ordem e o espaçamento.
2

Chave errada

A chave é o segredo do webhook (do dashboard), não a API Key.
3

Segredo rotacionado

Depois de Rotacionar segredo, o antigo deixa de assinar. Atualize o seu servidor.
4

Proxy alterando o corpo

Nginx, Cloudflare ou um API Gateway que reescrevem ou comprimem o corpo quebram a assinatura. Teste com o vetor de teste.
É esperado: a entrega é ao menos uma vez, e vem de novo quando a sua resposta não foi 2xx. Deduplique pelo id do evento (transaction.*) ou pelo X-NyxPag-Delivery (med.*).
Se você faz trabalho pesado antes de responder, estoura o limite de 8 segundos. Grave o evento numa fila, responda 2xx e processe fora do request.

​
Limites

Passou de 100 requisições em 60 segundos na chave.
1

Espere o Retry-After

Está no cabeçalho, em segundos.
2

Ache o que consome a cota

Quase sempre é polling com refresh=true. Troque por webhook.
3

Separe as cargas

Use uma chave para o checkout e outra para relatórios.
Veja Limites.

​
Saldo

O reserved guarda o que ainda não está livre: transferências em andamento e a parte de vendas retida pela política de reserva da conta. Ele é liberado ou debitado quando a operação termina. Veja Saldo.
Pode ser uma contestação MED. Consulte GET /meds. Veja Contestações (MED).

Erros

O catálogo completo de códigos de erro.

Antes de ir para produção

Evite os problemas antes que aconteçam.