Webhooks de pagamento
Receba e valide no seu servidor as confirmações de pagamento da VOIDpay.
- Configure no dashboard a URL pública HTTPS do seu endpoint.
- Defina um segredo de webhook e mantenha-o apenas no servidor.
- Ative os webhooks para a aplicação.
- Prepare o endpoint para aceitar requisições
POSTcom JSON.
Valide a assinatura antes de confiar nos dados ou alterar o estado de uma ordem.
payment.confirmed depois da confirmação do pagamento.{
"event": "payment.confirmed",
"orderId": "ord_123",
"status": "paid",
"amount": 1500,
"currency": "MZN",
"timestamp": "2026-10-19T13:20:00.000Z",
"transactionId": "txn_456",
"transactionReference": "ref_789",
"paymentMethod": "mobile_wallet",
"source": "api",
"sourceId": "ord_123",
"customer": {
"name": "Cliente Exemplo",
"email": "cliente@example.com",
"phone": "+258841234567"
},
"metadata": {
"appId": "app_123",
"appName": "Loja Exemplo",
"environment": "production"
}
}Os campos de transação, cliente, origem e referência podem variar conforme a compra e o método de pagamento. Os valores possíveis de source incluem api, invoice, payment_link, subscription e button.
Outros nomes de eventos podem estar definidos na plataforma, mas não estão ligados ao fluxo de compra atual. Não conte com notificações de falha de pagamento ou de reembolso até esses eventos serem ligados aos respetivos fluxos.
Content-Type: application/jsonX-Voidpay-Event: nome do evento enviado.X-Voidpay-Delivery: identificador único da entrega; repetições da mesma entrega reutilizam este identificador.X-Voidpay-Timestamp: data/hora ISO 8601 de criação do evento.X-Voidpay-Signature: assinatura HMAC, quando há um segredo configurado.
sha256=<hex> e usa HMAC-SHA256 sobre os bytes exatos do corpo HTTP.Valide sobre o corpo bruto, antes de converter o JSON. No Express, o middleware express.raw deve ser aplicado à rota antes de qualquer middleware que transforme o corpo em JSON.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const webhookSecret = process.env.VOIDPAY_WEBHOOK_SECRET;
function isValidWebhook(rawBody, signature, secret) {
if (!signature || !/^sha256=[a-f0-9]{64}$/i.test(signature)) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest();
const received = Buffer.from(signature.slice('sha256='.length), 'hex');
return received.length === expected.length &&
crypto.timingSafeEqual(received, expected);
}
app.post(
'/webhooks/voidpay',
express.raw({ type: 'application/json' }),
async (req, res) => {
const rawBody = req.body;
const signature = req.get('X-Voidpay-Signature');
if (!webhookSecret || !Buffer.isBuffer(rawBody) ||
!isValidWebhook(rawBody, signature, webhookSecret)) {
return res.sendStatus(401);
}
let event;
try {
event = JSON.parse(rawBody.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (event.event !== 'payment.confirmed') {
return res.sendStatus(200);
}
if (!event.orderId || event.status !== 'paid' ||
!Number.isFinite(event.amount) || !event.currency) {
return res.sendStatus(400);
}
const deliveryId = req.get('X-Voidpay-Delivery');
// Persist idempotently using deliveryId and orderId before acknowledging.
await savePaymentConfirmationOnce({ event, deliveryId });
return res.sendStatus(200);
}
);Substitua savePaymentConfirmationOnce pela persistência idempotente da sua aplicação. Nunca exponha o segredo no browser nem o escreva nos logs. Se a assinatura estiver ausente, confirme que o segredo está configurado antes de aceitar eventos sem validação.
- Responda com HTTP
2xxassim que o evento for validado e aceite. - Se o processamento demorar, guarde o evento de forma durável e processe-o depois.
- A VOIDpay tenta entregar até três vezes, com timeout de 15 segundos por tentativa.
Erros de rede e respostas 408, 425, 429 ou 5xx são temporários e podem ser repetidos. Outras respostas que não sejam 2xx são consideradas falha.
As tentativas decorrem durante o processamento da requisição de pagamento. Não existe fila persistente nem reenvio garantido após uma interrupção do servidor.
Antes de aplicar uma confirmação, verifique se a ordem já foi processada. Use orderId como chave de negócio e X-Voidpay-Delivery para reconhecer repetições da mesma entrega.
Só marque uma ordem como paga depois de validar a assinatura e confirmar os dados do evento. Guarde o evento antes de responder 2xx para evitar perder confirmações se o processamento interno falhar.