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

# Developer Reference

> Technical reference for the Khaime for WooCommerce plugin — API overrides, JavaScript API, and webhooks.

# Developer Reference

Technical details for developers integrating with or debugging the plugin.
Store owners don't need anything on this page — see [Configuration](/plugins/woocommerce/configuration) instead.

<Note>
  The plugin does not currently expose PHP action or filter hooks. The
  extension points are the JavaScript API and the webhook endpoint below.
</Note>

## Environments & API URL

The plugin selects its API host from the **Environment** setting:

* **Live**: `https://api.khaime.com/api/v1`
* **Sandbox**: `https://api.khaimedev.com/api/v1`

To point the plugin at a local backend, define the `KHAIME_API_URL` constant in
`wp-config.php`:

```php theme={null}
define('KHAIME_API_URL', 'http://localhost:3025/api/v1');
```

When set, it appears read-only under **Developer overrides** on the settings page.

## Diagnostics Panel

A live diagnostics panel (geolocation detection, active-currency resolution,
exchange-rate inspection, currency simulation, and a **Flush All Caches** button)
is available on the settings page — but **only in developer mode**: it appears
when `KHAIME_API_URL` points at a local host (`localhost`, `127.0.0.1`,
`*.local`, `*.test`). It is never shown on production stores.

## JavaScript API

The client-side price converter exposes a public API on `window.KhaimePriceConverter`:

```javascript theme={null}
// Switch the customer's currency and reload the page
KhaimePriceConverter.switchTo('NGN');

// Get the currently active currency code
KhaimePriceConverter.getActiveCurrency(); // 'USD'

// Re-scan the page and convert any new price elements
KhaimePriceConverter.convertAll('NGN');
```

Useful if you inject price elements via JavaScript (quick-view modals, infinite scroll).

## Webhook Endpoint

The plugin registers a REST endpoint to receive events from Khaime:

```
POST https://yourstore.com/wp-json/khaime/v1/webhook
```

### Security

Every request is verified before processing:

1. **Signature** — HMAC-SHA256 over the raw body using the webhook secret, from the `X-Khaime-Signature` header
2. **Deduplication** — each event's `X-Khaime-Event-Id` is checked against a 48-hour replay window
3. **Payload validation** — required fields are checked before processing

### Handled events

| Event                    | Action                                                        |
| ------------------------ | ------------------------------------------------------------- |
| `payment.succeeded`      | Marks order paid; stores transaction ID, amount, and currency |
| `payment.failed`         | Marks order failed; adds a note with the failure reason       |
| `subscription.created`   | Stores subscription ID, frequency, and next payment date      |
| `subscription.renewed`   | Processes the renewal                                         |
| `subscription.cancelled` | Cancels the subscription                                      |
| `refund.completed`       | Adds an order note confirming the refund                      |

### Logging

Webhook events log to **WooCommerce → Status → Logs** under the `khaime-webhooks`
source; API/currency activity logs under `khaimepay`.