> For the complete documentation index, see [llms.txt](https://docs.iyzico.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iyzico.com/en/platforms/woocommerce/woocommerce-integration-for-iyzico-kolai.md).

# WooCommerce Integration for iyzico kolai

kolai is the AI-powered shopping assistant available within the iyzico app. Users chat with kolai to get product recommendations and can purchase the recommended products directly through the iyzico app. This document explains the steps required in the iyzico panel and in WordPress to connect your WooCommerce store to kolai.

The integration consists of two separate stages:

1. **Preparation in the iyzico Panel** — introducing your products to kolai via XML and generating kolai API keys.
2. **Plugin Installation on WordPress** — installing and configuring the iyzico kolai for WooCommerce plugin.

The steps must be followed in order; the second stage cannot be started until the first stage is complete.

#### 1. Preparation in the iyzico Panel

**1.1 Upload Your Product XML**

For kolai to be able to recommend your products, the products in your store must first be introduced to iyzico via XML.

In the iyzico Merchant Panel, go to **Settings > Company Settings > Company Settings** tab and find the **"Upload Your Products with XML"** section.

<figure><img src="https://3756320043-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBnccQ14a3b6OedaJJFT4%2Fuploads%2FLdQWWbdc2S11joGyWG2L%2Fimage.png?alt=media&amp;token=d5118df5-48be-4a10-bdf5-bfbbf0b19ca1" alt=""><figcaption></figcaption></figure>

* In the **XML Link** field, enter the XML link listing the products in your store. The XML format must comply with the Google Merchant Center standard; you can check the Google Merchant Center page for details.

*You can find the XML format you should use for a sample product below:*

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:g="http://base.google.com/ns/1.0" version="2.0">
<channel>
<item>
<g:id>847362</g:id>
<g:title>Long-Lasting &amp; Matte Finish Lip Pencil Set</g:title>
<g:description>You can review the long-lasting and matte finish lip pencil set and buy it at affordable prices.</g:description>
<g:google_product_category>Home &gt; Makeup &gt; Lip Makeup &gt; Lipstick</g:google_product_category>
<g:product_type>Home&gt;Makeup&gt;Lip Makeup&gt;Lipstick</g:product_type>
<g:link>https://www.example.com/847362918273645</g:link>
<g:image_link>https://images.unsplash.com/photo-1586495777744-4413f21062fa</g:image_link>
<g:condition>new</g:condition>
<g:availability>in stock</g:availability>
<g:identifier_exists>yes</g:identifier_exists>
<g:mpn>84736291-001</g:mpn>
<g:brand>Example</g:brand>
<g:price>2329.99 TRY</g:price>
<g:sale_price>1249.99 TRY</g:sale_price>
<g:additional_image_link>https://images.unsplash.com/photo-1596462502278-27bfdc403348</g:additional_image_link>
<g:shipping>
<g:price>105.00</g:price>
</g:shipping>
</item>
</channel>
</rss>
```

* For **Update Interval**, choose one of Hourly, Daily, or Weekly. This determines how often your product list will be refreshed.
* Click the **Save** button.

> **Important:** The kolai product sales feature cannot be activated until your XML link has been reviewed and approved by iyzico. Make sure your XML is active and approved in the production environment.

**1.2 Activate Product Sales with kolai**

Once XML approval is complete, return to the **"Product Sales with kolai"** section on the same page (Settings > Company Settings).

Before the XML is approved, this section appears inactive.

<figure><img src="https://3756320043-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBnccQ14a3b6OedaJJFT4%2Fuploads%2FETSzgbEccSqmTw0OmuAG%2Fimage.png?alt=media&amp;token=ef6199fc-eb2e-48cc-b744-cf63d09b17ac" alt=""><figcaption></figcaption></figure>

Once the XML is approved:

1. Activate the **"I want to sell my products through kolai"** toggle.
2. In the **API Base URL** field, enter your store's domain address (e.g., `yourwebsitename.com`).
3. Select **WooCommerce** as the **Infrastructure Provider**.
4. Click the **Save** button.

<figure><img src="https://3756320043-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBnccQ14a3b6OedaJJFT4%2Fuploads%2FCjdvWrOgREJlmi7U4A6Q%2Fimage.png?alt=media&amp;token=bd0345a2-fdb6-4934-8b80-33bd512e68b0" alt=""><figcaption></figcaption></figure>

**1.3 Get Your kolai API Keys**

After the step above is saved, the **"kolai API Keys"** section becomes visible on the page.

<figure><img src="https://3756320043-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBnccQ14a3b6OedaJJFT4%2Fuploads%2FXNcxtyHUzw99g9hKuQuE%2Fimage.png?alt=media&amp;token=11177903-4e4b-4e8b-b55b-9532d8e01551" alt=""><figcaption></figcaption></figure>

* The **API Key** and **Security Key** are listed here; you can click the eye icon to view the values.
* If you want to renew the keys, you can use the **"Regenerate"** button.

Once these three steps are complete, the preparation on the panel side is finished and you can move on to installing the WordPress plugin.

#### 2. Plugin Installation on WordPress

At this stage, the `iyzico kolai for WooCommerce` plugin is installed and configured with the information obtained from the panel. You can access the plugin via [this link](https://github.com/iyzico/iyzipay-kolai-for-woocommerce).

**2.1 Prerequisites**

| Requirement | Minimum                   | Note                                                     |
| ----------- | ------------------------- | -------------------------------------------------------- |
| WordPress   | 5.0+ (tested with 6.9)    |                                                          |
| WooCommerce | 5.0+ (tested with 10.9.1) | Must be **active**; otherwise the plugin disables itself |
| PHP         | 7.2+                      | 8.1+ recommended                                         |
| HTTPS       | Required                  | kolai only sends requests to `https://` endpoints        |
| Permalinks  | Must **not** be "Plain"   | Detailed below                                           |

**Permalink setting — signature verification will fail if skipped:** On the **Settings → Permalinks** screen, an option other than "Plain" (e.g., "Post name") must be selected. The kolai signature is calculated based on the request's URL path (`/wp-json/kolai/v1/products`). If the permalink is "Plain," the REST call goes as `?rest_route=...`, the path becomes `/index.php`, and **all requests will return a 401 with an `Invalid signature` error.**

**Google Merchant XML:** The XML you uploaded in step 1.1 must be approved; kolai product matching cannot begin until it is approved.

**2.2 Install the Plugin**

**Via WP Admin:**

1. Download the ZIP file from GitHub for the `iyzipay-kolai-for-woocommerce` plugin.
2. **Plugins → Add New → Upload Plugin** → select the ZIP file → **Install Now**.
3. **Activate**.

> If WooCommerce is not active during activation, the plugin disables itself and displays a "kolai plugin requires WooCommerce" warning.

**Verification:** **kolai** should appear in the left menu, with "Agreements, Field Mapping, Logs" submenus underneath.

<figure><img src="https://3756320043-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBnccQ14a3b6OedaJJFT4%2Fuploads%2FuCQz13bG8Iu36lxem7fZ%2Fimage.png?alt=media&amp;token=20ae2d8b-b3f1-40ff-b7ea-5bb68d1c0420" alt=""><figcaption></figcaption></figure>

After installing the plugin, you can now configure it with your account information at this step.

**2.3 WP Admin → kolai → Settings**

<figure><img src="https://3756320043-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBnccQ14a3b6OedaJJFT4%2Fuploads%2FfNckOXudb6ImzLGk1G8r%2Fimage.png?alt=media&amp;token=ce715f41-ce9c-40ab-accf-5e17854d16e1" alt=""><figcaption></figcaption></figure>

**API Settings**

| Field                       | Description                                                                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Key**                 | The kolai API Key you obtained in step 1.3 in the iyzico panel                                                                                        |
| **Secret Key**              | The kolai Secret Key you obtained in step 1.3 in the iyzico panel. This is a masked field: if left blank, the saved value is retained and not deleted |
| **Clarification Text Page** | Selected from published WordPress pages; `GET /contracts/clarification-text` returns the content of this page                                         |

> If the API Key or Secret Key is blank, the plugin operates **fail-closed**: all kolai requests return a 401 with a `Server credentials not configured` error.

**iyzico Refund / Cancellation Settings** — must be filled in if refunds/cancellations will be processed through the WooCommerce panel.

| Field                  | Description                                                |
| ---------------------- | ---------------------------------------------------------- |
| **iyzico API Key**     | iyzico Merchant Panel API key                              |
| **iyzico Secret Key**  | Masked field; if left blank, the current value is retained |
| **iyzico Environment** | `Sandbox` for testing, **`Production`** for live use       |

If this information is not entered, order creation still works, but refunds/cancellations made from WooCommerce are not communicated to iyzico.

**Shipping Methods (iyzico)** — Lists the active methods in your WooCommerce shipping zones. Unchecking a method only hides it from the `/shipment-options` endpoint; it does not affect the normal WooCommerce checkout flow. Default: all enabled.

After filling in all fields, click **Save Settings**.

**2.4 WP Admin → kolai → Agreements**

The values on this screen automatically fill in the placeholders in the agreement templates.

**Merchant Information** (all required):

* Merchant Name / Title, Address, Phone, Email Address
* **Tax Identification Number (VKN)**
* **MERSİS Number**

**Delivery and Right of Withdrawal:**

* Estimated Delivery Date (e.g., "3 business days")
* Right of Withdrawal Period (e.g., "14 days")

**Agreement texts:** The Distance Sales Agreement and Preliminary Information Form come with default texts. Check them with your legal department and edit if necessary; if you're not editing them, accepting the defaults and saving is sufficient.

Click **Save Agreements**.

**2.5 Field Mapping (Optional)**

The **kolai → Field Mapping** screen lets you customize the meta key names written to the order (invoice type, TCKN/VKN, tax office, iyzico Payment ID, number of installments, installment fee, etc.). If your invoicing/accounting plugins expect different key names, map them here. You can also translate the `personal` / `company` invoice type values to the values expected by your own plugin.

> Changing a key name only affects **future** orders.

**2.6 Verify the Installation**

**Is the REST route up?**

Send an unsigned request from the terminal: curl -i <https://yourwebsitename.com/wp-json/kolai/v1/products>

**Expected:** HTTP `401` with the following body:

```json
{
  "status": "failure",
  "errorCode": "1005",
  "errorMessage": "Missing or invalid authorization header"
}
```

This response means "everything is correct": the route is registered, the permalink is correct, and authentication is active.

| Response you get | Meaning                                                   |
| ---------------- | --------------------------------------------------------- |
| `401` + `1005`   | ✅ Correct                                                 |
| `404`            | Permalink is still "Plain" or the plugin is not active    |
| `200` + data     | ⛔ Authentication is disabled — notify iyzico immediately. |
| `1004`           | WooCommerce is not active                                 |

**End-to-end test:**

1. On the **kolai → Logs** screen, check the "Enable Logging" box, set the level to `debug`, retention period to 7 days → save.
2. Trigger product listing / shipping options / a test order from kolai.
3. Check the `auth` and request records in the log table (personal data is masked).
4. Once go-live is complete, **turn off the logs** — they don't need to stay on continuously.

Things to check:

* Are products showing up with the correct price and VAT breakdown?
* Are shipping options returned with the correct region/fee?
* Is the test order being created in WooCommerce, with the address (city/district) filled in correctly?
* Does the order total exactly match iyzico's `paidPrice` (with an "Installment Fee" line for installment transactions)?
* Is a partial refund made from WooCommerce communicated to iyzico?

***

#### 3. Go-Live Checklist

**A. iyzico Merchant Panel**

* [ ] Production XML active in the XML field
* [ ] Google Merchant XML entered and approved
* [ ] kolai product sales feature active
* [ ] kolai API Base URL defined (your domain address)
* [ ] Infrastructure provider selection defined (WooCommerce)
* [ ] kolai API Key defined
* [ ] kolai Secret Key defined

**B. WordPress / WooCommerce**

* [ ] WooCommerce installed and active
* [ ] Site is live over HTTPS
* [ ] Permalinks are not "Plain"
* [ ] Plugin activated, "kolai" visible in the left menu

**C. kolai → Settings**

* [ ] API Key entered (identical to the value on the platform)
* [ ] Secret Key entered (identical to the value on the platform)
* [ ] Clarification Text page selected (page is published)
* [ ] iyzico API Key entered
* [ ] iyzico Secret Key entered
* [ ] iyzico Environment = Production (for go-live)
* [ ] Shipping methods reviewed

> iyzico keys are only required if refunds/cancellations will be processed through the WooCommerce panel; if so, be sure to fill them in.

**D. kolai → Agreements**

* [ ] Merchant name / title, address, phone, email entered
* [ ] VKN entered
* [ ] MERSİS number entered
* [ ] Estimated delivery date entered
* [ ] Right of withdrawal period entered
* [ ] Distance sales agreement text checked (or default accepted)
* [ ] Preliminary information form text checked (or default accepted)

**E. Verification**

* [ ] `curl https://yourwebsitename.com/wp-json/kolai/v1/products` → `401` + `1005`
* [ ] Product listing from kolai successful
* [ ] Shipping options returned correctly
* [ ] Test order created in WooCommerce, address and total correct
* [ ] Test refund communicated to iyzico
* [ ] Logs turned off after go-live

***

#### 4. Go-Live Request

Once all the items above are complete, send confirmation that you're ready to go live to [**entegrasyon@iyzico.com**](mailto:entegrasyon@iyzico.com).

**Sample email:**

> **Subject:** kolai go-live request — \[Store Name] / \[Merchant ID]
>
> Hello,
>
> We have completed all the required steps for the kolai WooCommerce integration:
>
> * Merchant Panel: production XML active, Google Merchant XML approved, kolai product sales active, Base URL + infrastructure provider + API/Secret Key defined.
> * WordPress: iyzico kolai for WooCommerce plugin installed and active; kolai API keys, clarification text page, iyzico refund/cancellation keys (environment: production), and agreement information (including VKN/MERSİS, delivery and right-of-withdrawal periods) entered.
> * Verification: `/wp-json/kolai/v1` endpoints respond with signature verification; test product listing, shipping options, order, and refund flows are successful.
>
> Store URL: \[yourwebsitename.com] Merchant ID: \[...]
>
> Ready to go live. Thank you.

***

#### 5. Troubleshooting

| Symptom                                    | Possible cause                                   | Solution                                                                |
| ------------------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------- |
| All requests return `Invalid signature`    | Permalink is "Plain"                             | Change your permalinks                                                  |
| `Server credentials not configured`        | API Key or Secret Key is blank                   | Enter them under kolai → Settings                                       |
| `Invalid client credentials`               | API Key doesn't match the value on the platform  | Copy the value exactly                                                  |
| `Replayed request rejected`                | The same request was resent with the same `salt` | Normal protection; the client must generate a new salt for each request |
| `Request timestamp outside allowed window` | Server clock has drifted                         | Sync the time using NTP (±300 sec)                                      |
| `1004 WooCommerce inactive`                | WooCommerce is disabled                          | Activate WooCommerce                                                    |
| Order `city` field is blank                | Outdated plugin version                          | Update the plugin                                                       |
| Order total doesn't match on installments  | Outdated plugin version                          | Update the plugin                                                       |
| Logs are empty                             | Logging is disabled                              | kolai → Logs → "Enable Logging"                                         |

For detailed technical documentation, see the README.md and the related AUTH.md / PRODUCT.md / ORDER.md / SHIPPING.md / CONTRACT.md / REFUND.md / LOGS.md files in the plugin repository.

#### 6. Plugin Download Link

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-kolai-for-woocommerce/archive/refs/heads/master.zip">kolai for WooCommerce</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.iyzico.com/en/platforms/woocommerce/woocommerce-integration-for-iyzico-kolai.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.