Skip to main content
Em vez de perguntar a cada segundo se o Pix foi pago, você deixa a NyxPag avisar. Quando uma transação muda de estado, a gente envia um POST assinado para a sua URL, e você reage. É o caminho recomendado para confirmar pagamentos: mais rápido que consultar, e não gasta a cota de 100 requisições por minuto da sua chave.

​
Como funciona

1

Você registra uma URL

No dashboard, ou no campo webhookUrl da própria requisição.
2

Algo acontece

Um Pix é pago, uma transferência falha, uma contestação é aberta.
3

A NyxPag envia um POST

O corpo é JSON e o cabeçalho X-NyxPag-Signature prova a origem.
4

Você valida e responde 2xx

Se não responder 2xx, a gente tenta de novo, até 8 vezes.

​
Eventos

​
Configurar

Há duas formas, e você pode combinar.
É o jeito recomendado, porque gera o segredo de assinatura.
1

Abra Webhooks

Acesse Dashboard → Webhooks.
2

Informe a URL e a chave vinculada

Em URL do endpoint, cole algo como https://seusite.com.br/webhooks/nyxpag e escolha a chave de API a que esse endpoint pertence.
3

Copie o segredo

O segredo de assinatura aparece uma única vez. Guarde no seu cofre de segredos. Se perder, use Rotacionar segredo.
Toda operação criada com essa chave passa a notificar esse endpoint.
Se a operação não tem webhookUrl e a chave não tem endpoint ativo, nenhum webhook é enviado. Você ainda consulta o estado por GET /transactions/{id}.

​
Regras da URL

A NyxPag recusa URLs inseguras na hora de configurar. Para passar na validação:
Se o seu endpoint redireciona (por exemplo de www para o domínio raiz, ou de http para https), a entrega falha. Cadastre a URL final, a que responde 2xx direto.

​
Entrega e retentativas

A NyxPag considera a entrega bem-sucedida somente com resposta 2xx em até 8 segundos. Qualquer outra coisa, incluindo timeout, 3xx, 4xx e 5xx, conta como falha e agenda uma nova tentativa. A espera dobra a cada falha e nunca passa de 1 hora. Os tempos são aproximados porque dependem do ciclo do reenvio.
Depois da 8ª falha a NyxPag não tenta mais. Se o seu servidor ficou fora do ar por muito tempo, concilie com GET /transactions filtrando por status. Veja Acompanhar transações.

​
O que isso significa para o seu código

  • Entrega ao menos uma vez. O mesmo evento pode chegar duas ou mais vezes. Deduplique.
  • Sem garantia de ordem. Um evento antigo pode chegar depois de um novo.
  • Responda rápido. Grave o evento, responda 2xx e processe fora do request.

​
Boas práticas

1

Valide a assinatura primeiro

Antes de qualquer efeito. Veja Validando a assinatura.
2

Deduplique de forma durável

Para transaction.*, use o id do evento. Para med.*, que não tem id de evento, use o cabeçalho X-NyxPag-Delivery.
3

Persista antes de responder 2xx

Se você responde 200 e a fila cai logo depois, o evento se perdeu e a NyxPag não tenta de novo.
4

Reconcilie periodicamente

Um job que lista as transações recentes cobre o caso de uma entrega ter esgotado as tentativas.
5

Não registre dados pessoais

O corpo traz nome, CPF e e-mail do pagador. Evite gravar em logs abertos.

​
Testando localmente

Como localhost é recusado, use um túnel HTTPS para expor a sua máquina:
Cadastre a URL https://... que o túnel devolver como endpoint em Dashboard → Webhooks. Para disparar um evento real, crie uma cobrança de valor baixo e pague pelo seu banco.
Não existe um botão “enviar evento de teste”. Por não haver sandbox, o teste é uma cobrança real de valor baixo. Veja Ambientes.

Validando a assinatura

HMAC-SHA256, vetor de teste e código em Node, Python e PHP.

Eventos de transação

Payload completo de transaction.approved, failed e cancelled.