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.

• 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 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.

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.

1.3 Get Your kolai API Keys

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

• 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.

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.

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

2.3 WP Admin → kolai → Settings

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:

{
  "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 [e-mail].

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

kolai for WooCommerce