WooCommerce
To accept payments through MONEI in your WooCommerce store you simply need to install and configure MONEI WooCommerce Plugin.
Live demo
Requirements
| Component | Minimum | Tested up to |
|---|---|---|
| WordPress | 5.0 | 7.0 |
| WooCommerce | 3.0 | 11.0 |
| PHP | 8.0 | 8.3 |
Plugin versions 7.0.1 and newer require PHP 8.0+. If you are still on PHP 7.4, upgrade PHP before updating the plugin — WordPress itself no longer supports PHP 7.4 either.
The plugin is compatible with:
- WooCommerce Blocks (Cart + Checkout) — see the migration section below
- High-Performance Order Storage (HPOS)
- WooCommerce Subscriptions and YITH WooCommerce Subscription for recurring billing with saved cards
Before you begin
To test your integration:
- Use your test mode API Key. You can find it in MONEI Dashboard → Settings → API Access.
- You can check the status of a test payment in your MONEI Dashboard → Payments (in test mode).
Install
The recommended path is wp-admin → Plugins → Add new → search for MONEI → Install → Activate. WordPress will automatically update the plugin going forward.
For a pre-release or a specific tag, download the ZIP from the GitHub releases page and upload it via Plugins → Add new → Upload Plugin.
Configure
Go to WooCommerce → Settings → MONEI Settings
Enter your Account ID and API Key. You can find your Account ID and API Key in MONEI Dashboard → Settings → API Access. Test and live credentials have separate fields — the Mode toggle decides which pair is active.
The rest of the page sets how every MONEI method behaves:
| Setting | What it does |
|---|---|
| API Key Mode | Which pair of credentials is active, Test or Live. |
| What to do after payment? | The status a paid order gets: Processing (recommended) or Complete. Use Complete only if nothing has to be packed or shipped. |
| Payment Action | Sale charges immediately. Authorization holds the money until you capture it — see Payment action. |
| Log Level | How much the plugin writes to WooCommerce → Status → Logs — see Troubleshoot. |
Go to WooCommerce → Settings → Payments
Configure payment methods that you want to accept in your store. Each MONEI method has its own settings panel where you can switch between component (inline form) and redirect (Hosted Payment Page) mode, customize the title and description, and theme the embedded form via JSON.
Card field layout
Under MONEI Cards, Card Field Layout decides how the card form looks.
Separate fields (default) — card number, expiry and CVC each get their own field. Focus moves from number to expiry to CVC as the customer types.
Single line — all three share one field, which suits a compact checkout.
Card Input Style themes both layouts from the same JSON, so switching layout keeps your styling. If you set a height in base, use the field's inner height — 48px for the default 50px field with its 1px border. The frame renders at exactly the height you give it, so a larger value is clipped at the bottom and a smaller one sits at the top, and either way the text leaves the middle.
Up to v7.2.4 the default was a single line. If you never chose a layout, your checkout moves to separate fields when you update — pick Single line under MONEI Cards to keep the old form. A layout you already selected is kept.
Whichever you pick, card details go straight to MONEI and your PCI DSS scope stays at SAQ A.
Saved cards
Under MONEI Cards, turn on Saved cards to let a customer reuse a card. At checkout they see Save payment information to my account for future purchases, and any card they saved appears the next time they pay.
Card details are stored on MONEI servers, never in your WordPress database. Saved cards are also what makes recurring billing work — see Subscriptions.
Supported payment methods
- Card (Visa, Mastercard, and more) — with for saved cards
- Apple Pay
- Google Pay
- Bizum (Spain — automatically hidden for non-Spanish customers)
- PayPal
- Multibanco (Portugal — hidden for non-Portuguese customers, redirect only)
- MB Way (Portugal — hidden for non-Portuguese customers, redirect only)
Express checkout
Express checkout puts an Apple Pay, Google Pay or PayPal button on your storefront. The customer pays from the wallet sheet, and the shipping and billing address comes from the wallet, so nobody fills in the checkout form. It works on both the classic checkout and the Cart and Checkout blocks.
Express checkout is available from plugin version 7.1.0.
To turn it on, go to WooCommerce → Settings → Payments, open MONEI Apple Pay / Google Pay or MONEI PayPal, and set:
| Setting | What it does |
|---|---|
| Express Checkout | Turns the button on. Off by default. |
| Express Checkout Button Locations | Where the button appears: Product page, Cart page, Checkout page. All three by default. |
| Express Checkout Button Style | Themes the button in JSON. |
Each method is independent — you can offer a wallet button on the product page only, and PayPal nowhere, if that is what suits your store.
The same conditions as the regular payment method apply. Apple Pay needs your domain registered, and the Apple Pay or Google Pay button only appears for a customer whose device and browser can pay with that wallet.
PayPal returns the shopper's name, email and country, and a street address only when the account has one saved. The Cart and Checkout blocks place the order through the WooCommerce Store API, which requires a complete billing address and refuses an incomplete one. The product page builds the order itself and accepts what PayPal sends. If a shopper is turned away, the store now says which fields are missing instead of failing silently.
For the equivalent in a custom integration, see Express checkout.
Subscriptions
The plugin bills subscriptions with either WooCommerce Subscriptions or YITH WooCommerce Subscription. Install one of them, and MONEI Cards and MONEI Apple Pay / Google Pay accept subscription products — the other MONEI methods do not.
Turn on Saved cards first. A renewal charges the token saved with the first payment, so without it there is nothing to charge on renewal day.
A customer changes the card behind a subscription from My account → Subscriptions → Change payment.
For subscriptions created through the API instead, see Subscriptions.
Payment action
WooCommerce → Settings → MONEI Settings → Payment Action decides when the money moves.
Sale (Immediate charge) — the default. The customer is charged as they pay.
Authorization (Pre-authorization) — the money is held on the customer's card and the order lands On hold. You capture it by moving the order to Processing or Completed, or release it by moving the order to Cancelled or Refunded. Both happen automatically as you change the status; there is no separate capture button.
Capture within 7 days of a card payment. After that the authorization is marked expired and can no longer be captured — you have to ask the customer to pay again. The window is set by the payment method, so it is not the same everywhere; see Payments for the one that applies.
Pre-authorization applies to Card, Apple Pay, Google Pay and PayPal. MB Way and Multibanco charge immediately whatever this setting says.
Before 7.2.4 those two charged immediately even with Authorization selected. Update the plugin if you rely on it.
Refunds
Refund from the order itself: WooCommerce → Orders, open the order and choose Refund. Enter the full amount or part of it, then use the refund button that names the MONEI payment method — not Refund manually, which only adjusts the order in WooCommerce and moves no money. The refund reaches MONEI straight away and the order gets a note with the result.
A refund that MONEI rejects also leaves a note on the order saying why.
Migration to WooCommerce Blocks
Starting from version 6.0, the plugin supports WooCommerce Blocks. To enable the modern checkout experience, replace the legacy shortcodes with the Cart and Checkout blocks.
Go to Pages and find the Checkout page. Remove the old shortcode and add the Checkout block to the page.
Go to Pages and find the Cart page. Remove the old shortcode and add the Cart block to the page.
Troubleshoot
Set WooCommerce → Settings → MONEI Settings → Log Level to INFO while you reproduce the problem, then read the log at WooCommerce → Status → Logs and pick the MONEI file.
Put the level back to ERROR afterwards. INFO writes a line for every payment step and costs performance on a busy store.
A payment method does not appear at checkout
- The method has to be active in MONEI Dashboard → Settings → Payment methods as well as enabled in WooCommerce.
- Bizum, MB Way and Multibanco hide themselves for a customer outside the country they serve.
- Apple Pay and Google Pay only appear on a device and browser that can pay with them. Apple Pay also needs your domain registered.
- The plugin caches which methods your account offers for 30 seconds, so a change in the dashboard takes a moment and a reload to show up.
An order stays Pending after the customer paid
MONEI confirms a payment over the IPN callback. If your store never receives it, the payment succeeds in the dashboard while the order stays Pending.
Check that https://<your-store>/wc-api/monei_ipn/ is reachable from outside — no IP allowlist, no bot protection in front of it, and permalinks saved at least once.
Before you go live
- Make sure that you are using live (production) mode API Key.
- Make sure that you have at least one active payment method.
- Verify the IPN URL
https://<your-store>/wc-api/monei_ipn/is reachable from MONEI (no IP allowlist, no Cloudflare bot block, permalinks saved). - For Apple Pay, register your domain in MONEI Dashboard → Settings → Payment methods.
- If you use Blocks checkout, confirm the Cart and Checkout pages use blocks (not shortcodes).