The Zahlo plugin (zahlo-pay) adds a Zahlo Checkout payment method to WooCommerce. It works with Classic checkout and Checkout Blocks, in two modes:
  • Hosted: the customer is redirected to Zahlo’s payment page and back to the order confirmation.
  • Embedded: the payment fields appear on your store’s order-pay page.
You write no code. The plugin creates one checkout session per order, moves orders to Processing only on a signed Zahlo event or a server-side check, and syncs refunds in both directions. You need: WordPress 6.0+, WooCommerce 8.0+ (9.5 tested), PHP 8.0+, and a Sandbox API key (zk_test_…) from the Developers page at https://merchant-demo.zahlo.eu.
WooCommerce Subscriptions is not supported. To sell subscriptions next to a WooCommerce store, use Subscriptions on a website or by link; see Not supported.
1

Install the plugin

In WordPress, open Plugins → Add New Plugin → Upload Plugin, choose the zahlo-pay zip you received from Zahlo, install it and click Activate. To install by hand, copy the zahlo-pay folder to wp-content/plugins/ and activate it under Plugins.
2

Paste your key and choose a mode

Open WooCommerce → Settings → Payments → Zahlo Checkout and:
  1. Tick Enable Zahlo Checkout.
  2. Paste your zk_test_… key into API key.
  3. Choose Hosted or Embedded under Checkout. Hosted is the default.
  4. Optionally change the title and description customers see at checkout.
  5. Click Save changes.
The settings page then shows Sandbox mode (test key) and the registered checkout domain. The key selects the environment: a zk_test_ key uses the Sandbox at https://merchant-demo.zahlo.eu, a zk_live_ key uses https://merchant.zahlo.eu.The method appears at checkout only when the key is valid and the store currency is one of CAD, CHF, DKK, EUR, GBP, JPY, PLN, RON or USD and enabled for your account. EUR is enabled by default; see Limits.
3

Register your domains

Saving the settings does this for you. The plugin registers:
  • the store’s checkout domain (Zahlo only redirects back to, and embeds checkout on, registered domains), with Apple Pay requested in Embedded mode;
  • a webhook endpoint at <your store>/?wc-api=zahlo_webhook for checkout, payment, refund and dispute events. The plugin keeps its signing secret.
Check both on the dashboard’s Developers page. If the store’s address changes, save the settings again.Local store. A zk_test_ key also works on http://localhost:<port>: the checkout domain registers, and orders move to Processing through the server-side check when the customer returns. Zahlo can’t deliver webhooks to localhost, so saving reports that the webhook endpoint could not be registered, and dashboard refunds and disputes don’t reach the order. For the full flow, expose the store through an HTTPS tunnel (for example cloudflared tunnel --url http://localhost:8080), set the public address in wp-config.php and save the settings again:
Apple Pay needs a public HTTPS domain, so it isn’t offered on localhost.
4

Place a test order

Add a product to the cart, check out, choose Zahlo Checkout and pay with the Sandbox test card 4111 1111 1111 1111, expiry 03/30, CVC 737.
  1. You land on the order confirmation page. The browser return alone never marks an order paid.
  2. The order moves to Processing once the signed checkout.session.completed event arrives (or the plugin’s server-side check confirms the session).
  3. The payment appears under Payments in the dashboard with your order number as its reference.
Test both checkouts if your theme offers them: Classic checkout and Checkout Blocks use the same method. Delivered and failed events are listed per endpoint on the dashboard’s Developers page.
5

Refunds and disputes

Refund from the WooCommerce order screen (Refund → Refund via Zahlo Checkout), in full or in part. If WooCommerce reports that the refund outcome is being confirmed, don’t refund again: it appears on the order once Zahlo confirms it. Refunds made in the Zahlo dashboard appear on the order automatically.When a customer disputes a payment, the plugin adds an order note. Respond in the dashboard under Disputes before the deadline; see Disputes.
6

Troubleshooting

  • Zahlo Checkout is missing at checkout: the key is missing or invalid, or the store currency is not enabled for your account.
  • Order stays Pending payment: a security plugin, a firewall or Cloudflare may block POST /?wc-api=zahlo_webhook. Allow it, then look at the endpoint’s deliveries on the Developers page.
  • “Could not register this store as a Zahlo checkout domain”: the message names the reason. A live key needs a public HTTPS hostname; localhost and IP addresses work only with a zk_test_ key.
  • “Payments are not available on this store”: a new account waits for Zahlo to approve its domain; the dashboard home shows the state.
  • Apple Pay doesn’t appear: the settings page shows the Apple Pay state and any error next to the checkout domain. It needs Embedded mode, a public HTTPS domain and a supported device.
7

Go live

Replace the zk_test_ key with a zk_live_ key and click Save changes. Saving registers the live webhook endpoint and the store’s live checkout domain, so the plugin covers steps 1, 4 and 5 of the checklist below. Products stay in WooCommerce, so step 2 doesn’t apply:Your live account starts empty, and Sandbox IDs, keys and secrets don’t work there. Recreate what this integration uses, in this order (details: Go live; your live dashboard’s Go live page at https://merchant.zahlo.eu/merchant/go-live tracks each step):
  1. Create a live API key and set ZAHLO_API_KEY to it (zk_live_…). Code that reads ZAHLO_API_BASE sets it to https://merchant.zahlo.eu.
  2. Run setup-catalog against live. It creates the same lookupKeys and coupon codes, so your code needs no change.
  3. Recreate your payment links; live links have new URLs.
  4. Add your live webhook endpoint, set ZAHLO_WEBHOOK_SECRET to its new signing secret, and confirm one live delivery arrives.
  5. Register your site’s checkout domain in live (HTTPS only), plus the Apple Pay domain if you embed checkout with wallets.
  6. Customers, subscriptions and saved payment methods don’t carry over; real checkouts create them.
  7. Make one small live payment, check that payment.confirmed and your fulfilment ran, then refund it.