Before you start
- FaltaPay is installed and activated. See Install and activate FaltaPay if you have not done this yet.
- You have API credentials from HyperPay, Tap Payments, or both. Test/sandbox credentials are enough to complete this guide.
Everything in this guide happens on FaltaPay > Settings, unless you use the guided setup wizard instead, which asks for the same information in a fixed order. Both write to the same settings, so you can start in one and finish in the other.
Choose a payment gateway
FaltaPay supports two payment gateways: HyperPay, through its COPYandPAY hosted form, and Tap Payments, through its hosted payment page. On the Payment gateways card, switch on the one your merchant account is with. You can switch both on at once; every integration you enable later can then be told which of them to offer.
Turning a gateway on or off reloads the page, because it changes which payment methods and credential fields exist. Nothing is charged by switching a gateway on; it only becomes usable once its credentials are entered and at least one payment method is switched on.
Test mode first
Before entering anything else, check the Test mode / Live mode switch at the top right of the Settings screen. FaltaPay keeps a completely separate set of credentials for test and live, so you can enter and verify test credentials without any risk of a real charge, then switch to live and enter your live keys separately later. The inactive mode’s credentials are never shown or touched by a save in the other mode.
Start in Test mode, walk through this whole guide, confirm a test payment reaches your gateway, and only then switch to Live mode and repeat the credential entry with your live keys.
Enter your gateway credentials
Once a gateway is switched on, a credentials card appears for it. Click Edit to open the fields. What each gateway asks for is different, because the two gateways authenticate differently.
HyperPay credentials
| Field | Required | Where to find it |
|---|---|---|
| Access token | Required | HyperPay dashboard → Account → API keys. Used for both one-time and recurring requests. |
| Webhook decryption key | Recommended | Shown once in HyperPay when you create the webhook. Without it, a shopper who closes the tab before returning to your site never gets their order marked paid. |
Tap credentials
| Field | Required | Where to find it |
|---|---|---|
| Secret key | Required | Tap dashboard → Developers → API credentials. Must start with sk_test_ in test mode or sk_live_ in live mode, matching the mode switch above. |
| Publishable key | Required | Same screen. Tap signs every payment request with it, so a payment cannot start without it. |
| Merchant ID | Optional | Only needed if Tap issued you one. |
Each credentials card also shows that gateway’s webhook URL. HyperPay needs you to paste this into its dashboard yourself; Tap is told the URL automatically with every payment, so there is nothing to paste for Tap. Webhook setup is covered in full in Webhooks and callbacks.
Click Save credentials. The gateway card shows Connected once credentials are saved; this only confirms something was entered, not that your gateway has accepted them yet. Use the Test button next to a payment method, described below, to check the credentials actually work.
Switch on payment methods
Scroll to the Payment methods card. This is where you choose which payment methods shoppers actually see, per gateway and per currency. Currencies here are detected automatically from the plugins you enable in Enable FaltaPay for your WordPress plugins, so set that up first if the list is empty; you can also add a currency by hand if your gateway account covers one no active plugin sells in yet.
The methods available depend on the gateway and the currency selected in the bar at the top of the card:
- Cards, with the individual schemes (Visa, Mastercard, American Express, JCB, Diners Club, Discover) selectable on HyperPay only. Tap has no scheme selector; it offers whatever your Tap account is enabled for.
- mada and STC Pay, SAR only.
- Apple Pay and Google Pay, on both gateways.
- American Express as its own method, for a HyperPay merchant with a separate Amex acquiring agreement.
- KNET (KWD) and Benefit (BHD), Tap only.
Switch a method on, then click Configure to open its settings panel. Tap methods generally need nothing further; your account credentials already cover them. HyperPay asks for an entity ID per method, because HyperPay issues a separate ID for every payment method and currency combination on your account. Paste the one-time entity ID from your HyperPay dashboard, and the recurring entity ID too if you plan to sell subscriptions and your gateway issued a separate one for that.
Each configured field has a Test button that checks your entered value against the gateway without creating a real transaction. Use it before moving on; it is the fastest way to catch a mistyped key.
A method’s status pill tells you what is stopping it:
| Status | Meaning |
|---|---|
| Off | The method switch is off. |
| Gateway not connected | The gateway’s credentials are missing or empty. |
| Entity ID missing / Recurring ID missing | HyperPay only. The one-time or recurring entity ID for this method is empty. |
| Wallet setup needed | Apple Pay or Google Pay needs the extra step covered below. |
| Ready | Shoppers can pay with this method now, wherever it is also switched on in an integration. |
A method being Ready here does not put it at checkout by itself. It also has to be switched on for the specific plugin you are selling through, which you set up on the Integrations screen.
Apple Pay and Google Pay setup
A Wallet setup card appears below Payment methods once you switch on Apple Pay or Google Pay for any gateway. Google Pay needs a Google Pay merchant ID from the Google Pay and Wallet console; this is required before Google Pay will work in live mode. Apple Pay’s domain association file field is optional: your gateway gives you this file when you register your domain with Apple, and it needs to be hosted at a fixed path on your site. Paste it here and FaltaPay serves it for you, or skip this field if you already host the file yourself.
Advanced settings
The Advanced card at the bottom of Settings covers three options most sites never need to change:
| Setting | Default | What it does |
|---|---|---|
| Transaction type | Charge immediately | Switch to Pre-authorise, capture later to hold funds instead of taking them straight away. Renewals always charge immediately regardless of this setting. |
| Log API requests and responses | Off | Turn on while you are setting things up; errors are always logged even when this is off. See Review payment logs. |
| Remove FaltaPay data on uninstall | Off | Leave this off to keep your credentials, gateway choices and method settings if you ever reinstall the plugin. |
Verify it works
You know configuration is complete when:
- The gateway card shows Connected.
- At least one payment method shows a Ready pill in the currency you sell in.
- The Test button next to that method’s fields returns success.
Next, turn FaltaPay on for the plugin you sell through: see Enable FaltaPay for your WordPress plugins.
Troubleshooting
The gateway card says “Needs credentials” after I saved. The card only reads whether every required field has a value, not whether the value is correct. Reopen the credentials form and use the Test button on a payment method below, which actually calls the gateway.
A HyperPay method stays on “Entity ID missing”. HyperPay issues one entity ID per payment method per currency. Check you pasted the ID for the exact method and currency you are configuring; an entity ID for cards in SAR will not work for cards in AED.
Tap’s Test button fails with an authentication error. Confirm the secret key’s sk_test_ / sk_live_ prefix matches the mode switch. A live key entered while Test mode is active, or the reverse, is rejected by Tap.
A payment method I expect to see is missing from the grid. mada and STC Pay only exist in SAR; KNET only exists in KWD; Benefit only exists in BHD. FaltaPay hides a method entirely outside its supported currency rather than showing it disabled.