O plugin expõe um endpoint REST que recebe as notificações da FaciPay e atualiza o estado das
ordens. É a fonte da verdade do pagamento.
Endpoint
POST https://a-tua-loja.com/wp-json/facipay/v1/incoming
Verificação HMAC
O header x-facipay-content-token contém o HMAC SHA-256 do body cru, calculado com o teu
Webhook Secret. O plugin valida-o com hash_equals (tempo constante) e aceita os formatos
sha256=…, sha256:…, hex cru ou base64.
Mapeamento de estados
| Estado recebido | Estado WooCommerce |
|---|
con / completed / paid / success | processing (pago) |
pen / pending / processing | on-hold (referência pendente) |
can / cancelled / expired / failed | failed |
refunded | refunded |
| outro | inalterado |
paymentId + estado e responde 200 sem
reprocessar se o mesmo evento chegar repetido.
Dados guardados na ordem
Para Referência EMIS pendente, o plugin guarda a referência, entidade e número de terminal
(_facipay_payment_reference, _facipay_payment_ref_entity_name,
_facipay_payment_ref_entity_number), além de cliente, taxa (_facipay_fee) e valor líquido
(_facipay_payout) — visíveis nos detalhes da ordem.
Respostas
| Código | Significado |
|---|
200 | Processado (ou já processado). |
400 | Campos em falta / JSON inválido. |
401 | Assinatura HMAC inválida. |
404 | Ordem não encontrada. |
Para desenvolvimento, existe a constante FACIPAY_SKIP_HMAC que (com WP_DEBUG) ignora a
validação HMAC. Nunca a uses em produção.
