Retorno e notificação

Os dois mecanismos são opcionais e independentes. Confirme o pagamento com Consultar link.

Retorno do pagador

redirect_url deve ser https absoluta. Qualquer host é aceito. Não é preciso cadastrar o domínio antes.

Depois que o pagamento fica PAID, o navegador do pagador abre a sua URL com esta query:

?id={uuid}&reference_id={reference_id}&status=PAID

Exemplo: https://loja.exemplo/retorno?id=018f1b2c-3d4e-7a89-b012-3456789abcde&reference_id=PEDIDO-123&status=PAID

Se a URL já tiver query, os campos são acrescentados com &.

Sem redirect_url, o pagador permanece no comprovante da Nuvende.

Use a query só para a experiência da loja. Ela não é o comprovante oficial. Sempre confirme com o GET, ou com a notificação.

Notificação

Se notification_url foi informada, a Nuvende envia um POST JSON quando o link fica PAID.

Regras da URL:

• Somente https.
• Host público. Localhost, IP privado e endereço de metadata são recusados.
• A Nuvende não segue redirecionamento.
• A sua URL deve responder com sucesso em poucos segundos.

Não há reenvio. Se o POST falhar, o pagamento não é desfeito. O status continua PAID. Consulte com GET.

Corpo

{
  "id": "018f1b2c-3d4e-7a89-b012-3456789abcde",
  "reference_id": "PEDIDO-123",
  "status": "PAID",
  "amount": 10000,
  "paid_at": "2026-09-09T15:00:00-03:00",
  "payment_method": "PIX"
}

amount está em centavos. payment_method é PIX, BOLETO ou CREDIT.

Segredo

Se você enviou notification_secret no create, o POST inclui:

Authorization: Bearer {notification_secret}

O segredo não vai na URL, nem na query do retorno. Trate o POST como não confiável até validar esse header, quando o segredo existir. Responda 2xx logo e processe o pedido na sua fila. Use id para não aplicar o mesmo pagamento duas vezes, caso você também consulte o GET.

Esta notificação não usa cadastro de webhook de outro produto. A URL é só o campo notification_url deste link.