# WooCommerce
Source: https://docs.zahlo.eu/quickstarts/ecommerce-woocommerce

The Zahlo plugin (**Zahlo Payments for WooCommerce**) 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.2+, WooCommerce 8.0+ (10.6 tested), PHP 8.0+, and a test-mode API key (`zk_test_…`) from the **Developers** page at `https://merchant.zahlo.eu` with **Test mode** on.

<Note>
Selling subscriptions? Install the WooCommerce Subscriptions extension next to the plugin: Zahlo saves the card at the first order and charges each renewal. See [Subscriptions](/integrations/woocommerce#subscriptions).
</Note>

<Steps>
<Step title="Install the plugin">

In WordPress, open **Plugins → Add New Plugin**, search for **Zahlo Payments for WooCommerce**, then click **Install Now** and **Activate**. Or upload the zip: **Plugins → Add New Plugin → Upload Plugin** with [zahlo-payments-for-woocommerce.zip](https://merchant.zahlo.eu/downloads/zahlo-payments-for-woocommerce.zip) (also under **Developers → WooCommerce** in the dashboard). Both install the same `zahlo-payments-for-woocommerce` folder, so a zip install also gets updates from WordPress.org.

Never edit the plugin files: an update replaces them. To keep the key in `wp-config.php` or add your own metadata, see [Customise](/integrations/woocommerce#customise).

</Step>
<Step title="Paste your key and choose a mode">

Open **WooCommerce → Settings → Payments → Zahlo Checkout** and:

1. Tick **Enable Zahlo Checkout** and keep **Test mode** on.
2. Paste your `zk_test_…` key into **Test API key**. Add your `zk_live_…` key under **Live API key** when you have one.
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 **Test mode** and the registered checkout domain. Both keys use `https://merchant.zahlo.eu`; the switch picks which key new orders use. Each order keeps the mode it was placed in, so refunds of test orders still work after you go live.

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](/limits).

</Step>
<Step title="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:

```php
define('ZAHLO_PAY_STORE_PUBLIC_URL', 'https://your-tunnel.trycloudflare.com');
```

Apple Pay needs a public HTTPS domain, so it isn't offered on `localhost`.

</Step>
<Step title="Place a test order">

Add a product to the cart, check out, choose **Zahlo Checkout** and pay with the 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.

</Step>
<Step title="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](/guides/disputes).

</Step>
<Step title="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.

</Step>
<Step title="Go live">

Paste your `zk_live_` key under **Live API key** if you haven't, turn **Test mode** off 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 Test-mode IDs, keys and secrets don't work there. Recreate what this integration uses, in this order (details: [Go live](/go-live#recreate-in-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 `lookupKey`s 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.

</Step>
</Steps>
