Aceite o seu primeiro pagamento FaciPay em sandbox em ~10 minutos: SDK, botão, backend e webhook.
Este guia leva você de zero a um pagamento de teste funcional. Vai carregar a SDK,
renderizar o botão e ligar um backend mínimo que cria a ordem e recebe o webhook.
A usar IA para programar? Salte para Construir com IA e copie
um prompt pronto que faz toda esta integração por si.
CLIENT_SECRET e WEBHOOK_SECRET ficam só no backend. Apenas a PUBLISHABLE_KEY
pode ir para o frontend. O applicationUUID usado na API é a PUBLISHABLE_KEYsem
o prefixo pk_test_/pk_live_.
O webhook é a fonte da verdade. Valide o HMAC sobre o body cru antes de JSON.parse.
Node.js (Express)
import crypto from 'node:crypto';// Registe o parser raw SÓ nesta rotaapp.post('/api/facipay/webhook', express.raw({ type: 'application/json' }), (req, res) => { const raw = req.body; // Buffer const token = req.headers['x-facipay-content-token']; const expected = crypto .createHmac('sha256', process.env.FACIPAY_WEBHOOK_SECRET) .update(raw) .digest('hex'); const a = Buffer.from(String(token)); const b = Buffer.from(expected); if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) { return res.status(401).end(); // assinatura inválida } const payload = JSON.parse(raw.toString('utf8')); const { externalTransactionId, paymentStatus } = payload.data; // Idempotência: se já está em estado final, responde 200 e sai // Atualiza a ordem: CON = pago, CAN = cancelado, PEN = pendente updateOrder(externalTransactionId, paymentStatus); res.status(200).json({ received: true }); });
O webhook é global / ao nível da conta: forneça o seu URL de webhook público à equipa
FaciPay para que o registe contra as suas credenciais (no onboarding ou via suporte). Não há
campo webhookUrl na ordem — o mesmo endpoint recebe todas as suas notificações.
Em desenvolvimento, exponha o seu webhook com um túnel (ngrok, Cloudflare Tunnel) e dê esse
URL público à FaciPay para o registar.