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.

1. Configure as variáveis de ambiente

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_KEY sem o prefixo pk_test_/pk_live_.

2. Carregue a SDK no frontend

3. Renderize o botão

O container tem de existir no DOM antes do .render().

4. Crie a ordem no backend

O frontend chama este endpoint dentro do createOrder(). Recalcule o total no servidor.
Node.js (Express)

5. Receba o webhook

O webhook é a fonte da verdade. Valide o HMAC sobre o body cru antes de JSON.parse.
Node.js (Express)
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.

6. Teste o fluxo

1

Multicaixa Express

Clique no botão → popup → confirme. Dispara onApprove e o webhook chega com CON.
2

Referência EMIS

Escolha Referência → o popup mostra entidade + referência. Dispara onPending.
3

Cancelar

Feche o popup sem pagar. Dispara onCancel.

Próximo passo: Conceitos essenciais

Chaves, ambientes, ciclo de vida da ordem e idempotência.