Zahlo Payments for WooCommerce

By zahloco

0+ active installationsVersion 2.2.0

Accept cards and wallets in WooCommerce with Zahlo: on Zahlo's payment page or embedded in your store, in test and live mode.

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_webhook and 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-sessions with 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 at https://payments.zahlo.eu (https://sandbox.payments.zahlo.eu in 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.js from 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, or https://sandbox.payments.zahlo.eu in 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/refunds from the WooCommerce order screen, and GET /api/v1/refunds to 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-methods to link and remove saved cards, and POST /api/v1/payments to 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.

Installation

  1. 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.)
  2. 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.
  3. In WooCommerce → Settings → Payments → Zahlo Checkout, paste the keys, keep Test mode on and choose Hosted or Embedded.
  4. Save. The plugin registers its webhook endpoint and checkout domain for each mode that has a key.
  5. 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.

Screenshots

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_KEY in wp-config.php to keep the API key out of the database; it takes precedence over the saved setting.
  • New: zahlo_pay_checkout_session and zahlo_pay_refund filters 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-Signature v1 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.