Skip to main content

​
Developer Reference

​
Intro

Technical details for developers integrating with or debugging the plugin — environment/API overrides, the client-side JavaScript API, and the webhook endpoint’s exact contract. Store owners don’t need anything on this page; see Configuration instead.

​
Context

This page assumes familiarity with the plugin’s configuration, payment flow, and webhooks pages — it’s the reference layer underneath them, for anyone debugging a local install or building something that reacts to plugin behavior in JavaScript.
The plugin does not currently expose PHP action or filter hooks. The extension points are the JavaScript API and the webhook endpoint below.

​
Hows

​
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:
When set, it appears read-only under Developer overrides on the settings page, and it overrides the Environment setting for both server-side calls and the JS switcher’s inline config.

​
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, ::1, *.local, *.test). It is never shown on production stores.

​
JavaScript API

The client-side price converter exposes a public API on window.KhaimePriceConverter:
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:

​
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

Refunds are not delivered through this endpoint — the plugin confirms a refund synchronously, in the same request that issues it from WooCommerce → Orders. See Payment Flow → Refunds. Event types outside this list (disputes, settlements, wallet activity, and others in the full webhook event catalog) are accepted and logged, but have no effect on the order — WooCommerce doesn’t have a corresponding concept for them.

​
Logging

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

​
Whys

The plugin exposes JavaScript hooks rather than PHP action/filter hooks because its extension surface today is genuinely client-side — price conversion and currency switching happen in the browser, so that’s where a merchant’s custom code (a quick-view modal, an infinite-scroll grid) needs to plug in. There’s no equivalent server-side extensibility need yet, which is why none exists. The webhook endpoint intentionally only acts on the small set of events that map to a WooCommerce concept (order status, subscription status) — every other event in Khaime’s catalog is delivered (so nothing is silently dropped or unauthenticated) but deliberately ignored, rather than the plugin guessing at a WooCommerce-side effect for events like disputes or settlements that have no natural home in an order.

​
Why nots

  • No PHP hooks yet. If you need to run custom server-side code around a Khaime payment event, you’d need to build against the REST webhook payload directly rather than a do_action()/apply_filters() call — there isn’t one today.
  • The diagnostics panel isn’t a production feature. It only renders when KHAIME_API_URL points at a local/dev host, by design — don’t expect it on a live store, even for admins.
  • Don’t rely on unhandled webhook events changing order state. Anything outside the “Handled events” table above is logged for visibility only; building a customization on top of an event the plugin doesn’t act on means writing your own handler against the raw payload.