Why webhooks matter
FaltaPay confirms a payment two ways: when the shopper is redirected back to your site, and independently, when the gateway calls a webhook URL to report the result. Both can mark the same order paid; FaltaPay only acts on whichever arrives first and ignores the other. The webhook is what saves a sale when the first path does not happen: a shopper who pays and then closes the browser tab before being redirected back never triggers the return path at all, so without a working webhook, that order stays unpaid even though the gateway took the money.
Each payment gateway you switch on gets its own webhook URL, found on its credentials card at FaltaPay > Settings:
https://yoursite.com/wp-json/faltapay/v1/webhook/hyperpay https://yoursite.com/wp-json/faltapay/v1/webhook/tap
Registering the callback URL
What you need to do here is different for each gateway.
HyperPay needs the URL pasted into its own dashboard, under Settings → Webhooks, along with the webhook decryption key HyperPay shows you once when you create it. Copy that key into the Webhook decryption key field on FaltaPay’s HyperPay credentials card straight away; it is not shown again by HyperPay after you leave that screen.
Tap needs nothing pasted anywhere. Tap is told the webhook URL automatically with every payment request FaltaPay sends, so there is no separate registration step and nothing to keep in sync.
Confirming delivery
FaltaPay records a timestamp every time a webhook body arrives and passes verification, including a gateway’s own test ping. Two places show this:
- The header of FaltaPay > Settings shows “last webhook received X ago” once anything has arrived, or “no webhook received yet” if nothing has.
- Inside the guided setup wizard’s credentials step, a status strip next to the webhook URL turns from a waiting spinner to “Notification received. The webhook is working” on its own, a few seconds after a test notification arrives. No page refresh is needed; it polls in the background.
Send a test notification from your gateway’s dashboard after saving the URL, and confirm one of these turns green before relying on it for real orders.
Test mode and live mode use separate credentials, and this matters here
The webhook URL itself does not change between test and live mode; only the key used to verify it does. FaltaPay always verifies an incoming webhook using whichever mode is currently switched on for your site, the Test/Live switch at the top of the Settings screen. This has one practical consequence: if you send a test notification from your gateway while your site is set to Live mode, or a live one while your site is set to Test mode, verification fails, because the key the webhook was signed or encrypted with does not match the key FaltaPay is currently checking against.
When you switch your site from test to live, re-check that a live webhook notification arrives and verifies; do not assume it still works just because test mode did.
What to check when a payment succeeds at the gateway but the order stays unpaid
- Check whether the shopper was ever returned to your site. If they were, and the order still failed to update, the problem is in the return path itself, not the webhook; check the logs for an error around that order.
- Check the webhook has been received at all, using the indicators above. If it has never fired for this gateway, the URL is likely not registered correctly, or nothing has reached it yet.
- Check FaltaPay > Logs for a rejected webhook. A rejected delivery is logged as an error, for example “Webhook rejected by hyperpay: The decrypted webhook payload was not valid JSON” or “…bad signature”. This almost always means the mode mismatch above, a mistyped decryption key or secret key, or a stale key from before you regenerated one in your gateway’s dashboard.
- Confirm your site is reachable from the public internet. A webhook is an inbound request from the gateway’s servers; a local development site, a staging site behind HTTP authentication, or a firewall or security plugin blocking unauthenticated
wp-jsonrequests will never receive it, even though everything looks correctly configured on both ends. - Check for a plugin or host rule blocking the REST API. Some security plugins disable or rate-limit
/wp-json/routes by default. FaltaPay’s webhook route needs to accept unauthenticated POST requests, since the gateway cannot log in to your site.
A note on renewals
A renewal charge that FaltaPay initiated itself (an automatic subscription payment) does not rely on its webhook to mark anything paid; the result is already recorded the moment the charge is made. If a webhook notification for a renewal still arrives afterwards, FaltaPay acknowledges it and does nothing further with it, rather than trying to process the same renewal twice.
Troubleshooting
The webhook status never turns green, and the log shows nothing at all. Nothing is reaching your server. Confirm the exact URL was saved in your gateway’s dashboard with no typos, and that your site does not require a password or IP allow-listing to reach it from the outside.
Requesting the webhook URL directly in a browser returns a 404. This is expected for a GET request; the route only answers POST. A 404 for a POST delivery from your gateway is different and means the gateway key in the URL itself is wrong, or that gateway is currently switched off in FaltaPay.
Everything verifies correctly in test mode but fails the moment I switch to live. This is almost always the mode mismatch described above: confirm you registered a live webhook secret (HyperPay) or that your live secret key (Tap) is entered, and that a fresh test notification was sent after switching.