> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komerza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WooCommerce

> Take payments through Komerza on your WooCommerce shop

Keep your WooCommerce shop exactly as it is and let Komerza take the payment. Customers shop and check out on your site as usual, pay on the Komerza checkout, and their order is marked paid in WooCommerce as soon as the payment arrives. Every sale also appears in your Komerza dashboard.

## How it works

1. At checkout, the customer chooses the Komerza payment option.
2. The plugin creates a Komerza order for the WooCommerce order's total and sends the customer to the Komerza checkout to pay.
3. Komerza tells your site when the payment arrives, and the WooCommerce order is marked paid.

Your products, cart, shipping and emails stay in WooCommerce. You do not need to add your products to Komerza.

## Requirements

* WordPress 6.2, WooCommerce 8.0 and PHP 7.4 or newer.
* A site reachable over HTTPS from the internet, so Komerza can report payments to it.
* A Komerza store with at least one [payment method](https://docs.komerza.com/guides/payment-methods.md) enabled, in the same currency as your WooCommerce shop.

## Set up

**1. Download the plugin**

Download [komerza-for-woocommerce.zip](https://github.com/komerza/woocommerce/releases/latest/download/komerza-for-woocommerce.zip), the latest release. Keep it zipped.

**2. Install it in WordPress**

1. In WordPress, go to **Plugins → Add New Plugin** and click **Upload Plugin**
2. Choose the zip file and click **Install Now**
3. Click **Activate Plugin**

**3. Create an API key**

1. In your Komerza dashboard, open **Developers → API Keys** and create a key
2. Name it something you will recognise, such as "WooCommerce"
3. Give it these permissions: **View Stores**, **View Orders**, **Create Orders**, **Create Webhooks** and **Delete Webhooks**
4. Copy the key

> [!WARNING]
>
> Komerza only shows the key once, when you create it. If you lose it, roll
> the key or create a new one.

**4. Copy your store ID**

In your Komerza dashboard, go to **Settings → General**. The **Store ID** is in the **Store** card, with a copy button next to it.

**5. Connect the plugin**

1. In WordPress, go to **WooCommerce → Settings → Payments** and open **Komerza**
2. Paste your API key and store ID
3. Choose a **Default payment method**
4. Tick **Offer Komerza at checkout** and click **Save changes**

The settings page confirms the connection, for example *Connected to My Store. Payments are taken in USD.* The plugin registers the webhook it needs in your Komerza account on its own, so there is nothing to set up under **Developers → Webhooks**.

Place a test order to make sure everything works, then refund it from your Komerza dashboard.

## Settings

| Setting | What it does |
| - | - |
| **Enable** | Offers Komerza at checkout. |
| **Title** | The name customers see at checkout. Defaults to *Pay online*. |
| **Description** | Shown when a customer chooses this option. Defaults to *You will be taken to Komerza to pay securely.* |
| **API key** | The key you created in Komerza. |
| **Store ID** | The Komerza store these sales belong to. |
| **Default payment method** | The method customers start on at the Komerza checkout. They can switch to any other method enabled on your store. |
| **Receipt** | Also sends customers the Komerza receipt. WooCommerce sends its own order emails either way, so this is off by default. |

## How orders are updated

The plugin keeps each WooCommerce order in step with the Komerza order paying for it.

| In Komerza | In WooCommerce |
| - | - |
| Paid | **Processing**, or **Completed** when every item is a virtual download. The Komerza order ID becomes the transaction ID. |
| Payment detected and confirming, or under review | **On hold** |
| Cancelled or expired | **Failed**, so the customer can try paying again |
| Refunded | **Refunded** |
| Disputed | **On hold**, with a note |

A WooCommerce order is only marked paid when Komerza has taken at least its total, in the same currency. Anything else is put on hold with a note, so you can check the payment in Komerza before fulfilling the order.

## Refunds

Refund the order from your Komerza dashboard. The WooCommerce order is marked refunded automatically.

> [!WARNING]
>
> Refunding an order inside WooCommerce does not return any money to the
> customer. Always refund from Komerza.

## Currency and taxes

Komerza charges in your Komerza store's currency, so the payment option only appears at checkout when your WooCommerce shop uses the same currency. If they differ, the plugin's settings page tells you.

Komerza charges the total WooCommerce calculates, taxes included. If tax collection is enabled on your Komerza store and set to **Exclusive** (under **Settings → Tax**), Komerza adds its tax on top and customers are taxed twice. Set it to **Inclusive**, or turn tax collection off if you only sell through WooCommerce.

> [!NOTE]
>
> With [Komerza Pay](https://docs.komerza.com/guides/payment-methods.md), Komerza is the seller and adds
> VAT where it applies, so a customer paying with Komerza Pay can pay more than
> the WooCommerce total.

## Updating the plugin

Download the latest release and upload it the same way you installed it. WordPress asks whether to replace the version you have. Choose **Replace current with uploaded**. Your settings are kept.

## Troubleshooting

> [accordion] Komerza does not appear at checkout
>
> Open the plugin's settings. Check that **Offer Komerza at checkout** is ticked, that the page says you are connected, and that your WooCommerce currency matches your Komerza store's.

> [accordion] Saving the settings shows an error
>
> Check the API key and store ID, and that the key has all five permissions listed above. If the key was deleted or rolled in Komerza, create a new one and paste it in.

> [accordion] An order stays on Pending payment after the customer paid
>
> Komerza could not reach your site to report the payment. Make sure your site is reachable over HTTPS from the internet, and that no security plugin or firewall blocks requests to `?wc-api=komerza`. The **Webhook Execution Logs** card on the order's page in your Komerza dashboard shows each attempt and why it failed.

> [accordion] I moved my site to a new address
>
> Open the plugin's settings and click **Save changes**. The plugin registers its webhook again at the new address.

> [accordion] Where can I see what went wrong?
>
> In WordPress, go to **WooCommerce → Status → Logs** and choose the log named **komerza**.

## Removing the plugin

Deactivate and delete it under **Plugins**. Deleting the plugin removes its webhook from your Komerza account and its settings from WordPress. Your orders keep their Komerza order IDs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.