Kalatori Payment Gateway for WooCommerce

WooCommerce payment gateway plugin for accepting cryptocurrency payments via a self-hosted Kalatori daemon.

Requirements

• WordPress ≥ 6.0
• PHP ≥ 8.0
• WooCommerce (declared as a required plugin — WordPress enforces this automatically)
• USD-denominated WooCommerce store
• WordPress permalink structure set to anything other than Plain (required for the webhook endpoint to resolve)

Installation

1. Build or download the plugin ZIP (see Building).
2. In WordPress admin: Plugins → Add New → Upload Plugin, select the ZIP, and activate.
3. Go to WooCommerce → Settings → Payments → Kalatori (Crypto) and enter your daemon URL and secret key. (Optional)

Configuration

Option A — WooCommerce admin UI

Enter the values at WooCommerce → Settings → Payments → Kalatori (Crypto).

Option B — Config file (pre-baked credentials)

Drop a woocommerce-kalatori-config.json file next to the main plugin PHP file. It is loaded once on first boot if the database option is still empty:

{
  "daemon_url": "https://pay.yourshop.com",
  "secret_key": "your-hmac-secret"
}

Do not commit this file. It is gitignored.

Building

bin/bundle.sh creates a distributable ZIP ready for WordPress upload. All flags are optional.

./bin/bundle.sh                                          # generic ZIP, no pre-baked config
./bin/bundle.sh --daemon_url <url> --secret_key <key>  # pre-configured ZIP
# Output: kalatori-woocommerce-plugin.zip

When at least one flag is provided, the values are baked into the ZIP as woocommerce-kalatori-config.json and loaded automatically on first install. Otherwise no config file is included and the merchant configures the gateway via the WooCommerce admin UI.

Webhook

Plain permalinks are not supported. WordPress must use a non-plain permalink structure (e.g. "Post name") for the REST API — and therefore the webhook — to work. If plain permalinks are detected, the plugin displays a warning in its settings page and hides itself from the checkout.

The plugin exposes a webhook endpoint that your Kalatori daemon should call when invoice status changes:

POST /wp-json/kalatori/v1/webhook

Configure this URL in your daemon. All requests must be HMAC-SHA256 signed using the same secret_key configured in the plugin.

The plugin validates two headers on every incoming webhook:

Requests that pass signature validation are deduplicated by event UUID for 24 hours — safe to retry on network errors.

Order status mapping

Reconciliation

The plugin schedules an hourly background job (via WooCommerce Action Scheduler) that polls the daemon for any on-hold orders whose webhooks may have been missed. Orders that received a webhook within the last 90 minutes are skipped.

To trigger reconciliation manually:

npx wp-env run cli wp action-scheduler run --hooks=kalatori_reconcile_orders

Or via WooCommerce → Status → Scheduled Actions.

Releasing

1. Update Version: x.y.z in kalatori-woocommerce-plugin.php.
2. Commit and push to main.
3. Tag and push:

   git tag v1.0.0
   git push origin v1.0.0

GitHub Actions builds the plugin ZIP and publishes it as a GitHub Release automatically. The version in the ZIP is set from the tag name.

Local development

Uses wp-env (requires Node.js and Docker):

npx wp-env start
./bin/setup-demo-data.sh

This creates demo products and pre-configures the gateway pointing at http://host.docker.internal:8080.

Configure your Kalatori daemon to send webhooks to:

http://host.docker.internal:8888/wp-json/kalatori/v1/webhook