Description
Zahlo lets your WooCommerce store take card and wallet payments. Paste your Zahlo API keys, choose how customers pay, and the plugin sets up the rest.
- Test mode and live mode — Keep a test key and a live key side by side. With Test mode on, orders use the Zahlo sandbox and no real money moves; turn it off to take real payments. Each order remembers its mode, so refunds and webhooks for earlier test orders keep working after you go live.
- Hosted or embedded — Hosted sends the customer to Zahlo’s payment page. Embedded shows the payment fields on your store’s order-pay page. Both work with Classic checkout and Checkout Blocks.
- Automatic setup — Saving the settings registers this store’s webhook endpoint and checkout domain with Zahlo, for each mode that has a key.
- Signed webhooks — Orders move to Processing only on a signed Zahlo event (or a server-side check on return), never on the browser redirect alone. Each event is applied once, even if it is delivered twice or out of order.
- Refunds — Refund from the WooCommerce order screen, in full or in part. Refunds made in the Zahlo dashboard appear on the order automatically.
- Disputes — A dispute puts a paid order on hold and emails you. A won dispute restores the order’s status; a lost one marks it failed.
- Exact totals — Products, shipping and fees are sent as their own lines, tax included; WooCommerce stays the source of tax and shipping.
- WooCommerce Subscriptions — The first order saves the card; renewals charge it without the customer present. A declined renewal puts the subscription on hold, and customers can change their card from their account.
- Saved cards — Optionally, logged-in customers can save their card; they manage saved cards under My Account Payment methods.
Requirements:
- A Zahlo merchant account (zahlo.eu)
- WooCommerce 8.0 or later (10.6 tested), PHP 8.0 or later, WordPress 6.2 or later
External services
This plugin connects to the Zahlo merchant API at https://merchant.zahlo.eu, for both test and live keys (the key selects the mode). Zahlo creates payment sessions, hosts the payment page and the embedded checkout script, and confirms payments. The plugin contacts it only as listed here:
- Settings save (server): verifies each key (
GET /api/v1/checkout-domains), then registers the webhook endpoint/?wc-api=zahlo_webhookand this store’s domain (POST /api/v1/webhook-endpoints,POST /api/v1/checkout-domains). When the store’s URL or key changed, it replaces the old endpoint (GET/DELETE /api/v1/webhook-endpoints), and after an update it adds new event types to it (PATCH /api/v1/webhook-endpoints/{id}). Sent: the store’s URL and domain. - Order placement (server):
POST /api/v1/checkout-sessionswith the order lines, amounts, currency, billing email, order number and ID, and return URLs. In Hosted mode the customer is then sent to Zahlo’s payment page athttps://payments.zahlo.eu(https://sandbox.payments.zahlo.euin Test mode). - Return page (server):
GET /api/v1/checkout-sessions/{id}to confirm the order’s payment. - Embedded checkout (browser): the order-pay page loads
/sdk/v1/zahlo.jsfrom Zahlo with a short-lived client token. That script loads Zahlo’s checkout script (/sdk/v1/checkout.js) from the same origin and shows the payment fields in a frame from Zahlo’s payment page (https://payments.zahlo.eu, orhttps://sandbox.payments.zahlo.euin Test mode). Card details are entered only in those fields and go to Zahlo and its card processor, never to the store. - Webhooks (server): Zahlo sends signed events (
Zahlo-Signature) to/?wc-api=zahlo_webhook. For a refund or dispute that names only a payment, the plugin looks the payment up (GET /api/v1/payments/{id}) to find its order. - Refunds (server):
POST /api/v1/refundsfrom the WooCommerce order screen, andGET /api/v1/refundsto confirm a refund whose outcome was not known yet. - Saved cards and renewals (server):
POST /api/v1/customers(the account’s email and name) when an account first saves a card,GET/DELETE /api/v1/customers/{id}/payment-methodsto link and remove saved cards, andPOST /api/v1/paymentsto charge a saved card for a subscription renewal.
This service is provided by Zahlo: Terms of use, Privacy policy.
Upgrade and removal
- 2.2.0 moves your existing key into the Test or Live key field that matches it and sets Test mode to match, so checkout keeps working. Add the other key when you have it.
- Deactivation keeps orders, settings and the event table.
- Deleting the plugin removes its settings (including the API keys), webhook secrets, checkout domains, saved Zahlo customer IDs, scheduled jobs and the event table. Orders and their notes stay in WooCommerce.
Troubleshooting
- Gateway missing at checkout: the active mode has no valid key, or the store currency is not enabled for your Zahlo account.
- “Payments are not available on this store yet”: new accounts wait for Zahlo’s domain approval; the Zahlo dashboard home shows the state. Save the plugin settings again if the store domain changed.
- Order stays Pending payment: check that security plugins or Cloudflare do not block
POST /?wc-api=zahlo_webhook, and look at the deliveries for the endpoint in the Zahlo dashboard (Developers Webhooks). - Refund “is being confirmed”: Zahlo has not yet confirmed the refund with the payment provider. It appears on the order once confirmed; do not refund again.
- Live mode on localhost: live checkout needs a public HTTPS hostname. Use Test mode locally.
Screenshots





Installation
- In WordPress, go to Plugins Add New Plugin, search for Zahlo Payments for WooCommerce, then Install and Activate. (Or upload the zip from the Zahlo dashboard, Developers WooCommerce.)
- In the Zahlo dashboard, create a test API key (
zk_test_…) while the dashboard is in test mode, and a live key (zk_live_…) in live mode when your account can take payments. - In WooCommerce Settings Payments Zahlo Checkout, paste the keys, keep Test mode on and choose Hosted or Embedded.
- Save. The plugin registers its webhook endpoint and checkout domain for each mode that has a key.
- Place a test order with the test card
4111 1111 1111 1111(any future expiry, any CVC). To go live, turn off Test mode and save.
Local stacks can override origins in wp-config.php: ZAHLO_PAY_MERCHANT_API_URL, ZAHLO_PAY_MERCHANT_PUBLIC_API_URL and ZAHLO_PAY_STORE_PUBLIC_URL. ZAHLO_PAY_API_KEY in wp-config.php keeps a key out of the database; it fills the key field of its own mode.
FAQ
-
Which payment methods are supported?
-
Cards and the wallets enabled for your Zahlo account (Apple Pay in embedded mode once your domain is registered for it). Subscription renewals and saved cards are cards only.
-
How do I test before going live?
-
Keep Test mode on and use your
zk_test_key. Test orders are marked “Zahlo test mode” on the order and never move real money. When you turn Test mode off, new orders use the live key; earlier test orders keep using the test key for refunds. -
Is it secure?
-
Yes. Card details are entered only in Zahlo’s payment fields and never pass through your store. Webhooks are signed with HMAC-SHA256 and checked against the order and its mode before anything changes.
Reviews
There are no reviews for this plugin.
Contributors & Developers
“Zahlo Payments for WooCommerce” is open source software. The following people have contributed to this plugin.
ContributorsTranslate “Zahlo Payments for WooCommerce” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
2.2.0
- Renamed to Zahlo Payments for WooCommerce, published in the WordPress.org plugin directory.
- Test mode: separate test and live API keys with a Test mode switch. Each order keeps the mode it was paid in, so its refunds, renewals and webhooks use the right key after you switch.
- Saving the settings registers a webhook endpoint and checkout domain for each mode that has a key.
- Upgrading moves your existing key into the matching field.
- Removed: the plugin no longer changes WordPress’s HTTPS detection or rewrites site URLs behind proxies; set that in wp-config.php if your host needs it.
2.1.0
- WooCommerce Subscriptions: the first order saves the card, renewals charge it off-session, a decline puts the subscription on hold, and customers can change their card.
- Saved cards (optional): customers can save a card at checkout and remove it under My Account Payment methods.
2.0.6
- Disputes put a paid order on hold; a won dispute restores its status, a lost one fails it.
- Ships a translation template and a German (de_DE) translation.
2.0.5
- Declares compatibility with the WooCommerce Cart and Checkout blocks, so the block editor no longer flags the plugin as incompatible.
- Tested with WordPress 7.1 and WooCommerce 10.6.
2.0.4
- Fix: in embedded mode, clicking “Place order” twice no longer leaves the order-pay page without the payment form.
2.0.3
- New: define
ZAHLO_PAY_API_KEYin wp-config.php to keep the API key out of the database; it takes precedence over the saved setting. - New:
zahlo_pay_checkout_sessionandzahlo_pay_refundfilters add your own metadata (and a checkout reference) without editing the plugin. Amounts, currency and the plugin’s own keys can’t be changed through them.
2.0.2
- Fix: a refund could be recorded in WooCommerce more than once when several background jobs for one order ran together, so the order showed more refunded than Zahlo returned and later refunds were refused. Each Zahlo refund now gets exactly one WooCommerce refund, checked against the database.
- Fix: “A Zahlo refund is still unconfirmed after 24 hours” could appear minutes after the refund. It now appears only after 24 hours, and one order keeps one retry schedule.
2.0.1
- Fix: a payment confirmed by two requests at once (webhook and thank-you page, or two webhooks) completed the order twice, reducing stock and sending the order emails twice. Completion now re-reads the order under its lock.
2.0.0
- One API key; the environment and origins come from the key prefix.
- Webhook endpoint and checkout domain register automatically;
Zahlo-Signaturev1 verification with a durable event inbox. - Embedded checkout on the order-pay page (Classic and Blocks); hosted redirects straight to Zahlo.
- Refunds from WooCommerce admin; dashboard refunds sync back to the order.
- Order lines include shipping, fees and tax; currency guard; correct JPY amounts.
- Removed: the legacy card/Apple Pay/Google Pay gateways, the
/checkout/{success,failure,cancel}return routes and the old product subscription plans.
