Integração API
Receber e depurar callbacks
Observe as notificações da plataforma e valide assinatura, respostas e duplicatas no seu próprio serviço.
Guia passo a passo
Siga as etapas no seu painel. Clique em uma imagem para ampliá-la.
Abra o receptor de callbacks e informe Merchant UID e API Key. Copie o notifyUrl de depuração para os pedidos que deseja observar ou selecione Usar URL de depuração na ferramenta de pedidos.
Etapa 1 · Clique para ampliar Inicie a recepção para atualizar a cada quatro segundos e ver até os 20 registros mais recentes enviados a esse endereço. Atualizar agora consulta imediatamente. Parar apenas pausa as consultas da página; não cancela pedidos nem desativa o receptor do servidor. Pedidos com outro notifyUrl não aparecem aqui.
Recebimentos enviam completed após o processamento bem-sucedido. Pagamentos enviam o estado final confirmed ou failed. Um pedido recém-criado, não pago ou em confirmação ainda não tem callback de sucesso. Compare pedidos, moeda, valor, hash, assinatura e entrega. A verificação no receptor de depuração não comprova que seu sistema processou o recebimento.
Para seu serviço, use o exemplo completo Node.js ou PHP do receptor. Publique-o em uma URL HTTPS acessível e preserve rawBody. Com a API Key do pedido original, calcule HMAC-SHA256(timestamp + "." + nonce + "." + rawBody) e compare com x-callback-signature. Não reformate o JSON nem substitua a assinatura do callback por x-signature.
Após verificar a assinatura, confira lojista, vínculo do pedido, rede, moeda, valor e estado final. Use transações e restrições únicas no banco para atualizar uma única vez. Retorne HTTP 2xx somente após processar com sucesso ou persistir com segurança em uma fila. Rejeite assinaturas inválidas e não informe sucesso se seu serviço falhar.
Teste com uma chave fictícia local: callbacks válidos passam, body alterado falha, duplicatas atualizam uma só vez e interrupções podem ser recuperadas. Depois configure seu notifyUrl e confira logs, respostas e pedidos. Timeout ou resposta diferente de 2xx permite até três tentativas: a segunda um minuto após a primeira falha e a terceira cinco minutos após a seguinte. Não há tentativas ilimitadas.
Se não chegar um callback, confira o status final, notifyUrl, UID, acesso HTTPS, assinatura do corpo original e resposta HTTP. O receptor de depuração não substitui a validação do seu serviço. Não registre a chave completa.