Before you start
- WooCommerce is active and its currency is set to one you sell in with FaltaPay.
- The WooCommerce integration is switched on at FaltaPay > Integrations, with at least one payment method offered to it. See Enable FaltaPay for your WordPress plugins.
Where FaltaPay appears at checkout
FaltaPay does not add one combined “FaltaPay” option to WooCommerce. It registers a separate payment option for every payment method you have switched on for WooCommerce, so a store offering Cards and mada through HyperPay shows two rows at checkout: Cards and Mada. If you also switch on Tap for the same method, a shopper would see two card options, one per gateway. This is how WooCommerce’s own payment gateway system works; FaltaPay does not change it.
This works with both the classic checkout and the WooCommerce Blocks (Cart and Checkout block) checkout: each FaltaPay method registers itself with both automatically.
Customise how a method appears
Each FaltaPay payment method is a normal WooCommerce payment gateway, so it is configured the normal WooCommerce way. Go to WooCommerce > Settings > Payments, find the row for the method (labelled FaltaPay {gateway}: {method}, for example FaltaPay HyperPay: Cards), and click Manage.
| Setting | Default | Notes |
|---|---|---|
| Enable/Disable | Off | This is separate from the FaltaPay switches. A method has to be ready in FaltaPay and enabled here to reach the checkout. |
| Title | The method name, e.g. “Cards” | What the shopper sees at checkout. |
| Description | “You will be taken to {gateway} to complete your payment securely.” | Shown under the title at checkout. |
| Order status after payment | WooCommerce default | WooCommerce normally moves a paid order to Processing, or Completed if every item is virtual or downloadable. Choose a specific status here to always use that one instead of WooCommerce’s default logic. |
Credentials and entity IDs are not on this screen. They live once on FaltaPay > Settings and apply to every plugin, so editing them here is not possible; the method’s description links back to that screen as a reminder.
Order statuses you will see
| Status | When it happens |
|---|---|
| Pending payment | Set the moment the shopper is redirected to the gateway. |
| On hold | The transaction type is set to pre-authorise rather than charge immediately, and the authorisation succeeded but has not been captured yet. See the Advanced setting in Configure FaltaPay. |
| Processing / Completed / your chosen status | Payment succeeded and settled. Which one depends on the order’s contents and the Order status setting above. |
| Failed | The gateway declined the payment or FaltaPay could not verify the result. |
A successful payment adds an order note with the FaltaPay transaction ID and whether it was confirmed on the shopper’s return to your site or by the gateway’s webhook arriving afterwards, for example “FaltaPay payment completed. Transaction ID: 8ac7a4c8… (webhook)”. Both paths can fire for the same order; FaltaPay only acts on whichever arrives first and ignores the other.
Subscriptions
Recurring payments through WooCommerce need the separate WooCommerce Subscriptions plugin. FaltaPay does not run its own renewal schedule for WooCommerce: WooCommerce Subscriptions owns the schedule and calls FaltaPay to make each charge when a renewal falls due.
A payment method only appears at checkout for a subscription product if it can actually be renewed automatically, which needs a card-storing gateway (see recurring payment support per platform). A method that cannot store a card, such as STC Pay or American Express on HyperPay, is hidden from a subscription checkout entirely rather than taking a first payment it could never charge again.
If a renewal fails because the stored card was declined or the gateway that took the original payment is now switched off, WooCommerce Subscriptions marks the renewal order Failed with the reason in an order note.
Refunds
Issue a refund from WooCommerce as you normally would: open the order, click Refund, enter the amount, and click Refund manually or the equivalent button for the gateway. FaltaPay sends the refund to whichever gateway actually took the payment, even if you have since switched to a different one or switched the original gateway off, so past orders always refund correctly.
A successful refund adds an order note with the refunded amount and the gateway’s refund transaction ID. See Refunds and transactions for what happens gateway-side and what a failed refund looks like.
Troubleshooting
A payment method does not appear at checkout even though it shows Ready on FaltaPay’s Settings screen. Check three things in order: it is switched on for the WooCommerce integration on the Integrations screen, it is enabled in WooCommerce > Settings > Payments, and it exists in your store’s currency. mada, STC Pay, KNET and Benefit are limited to a single currency each.
A subscription product hides a method that works fine for one-time orders. That method cannot store a card with the gateway you configured it on. Switch on the recurring entity ID (HyperPay) or check the method is one Tap can tokenize (cards and mada only).
The order stayed on Pending after the shopper paid. See Webhooks and callbacks for how FaltaPay confirms a payment and what to check when the gateway and WooCommerce disagree.