Requirements
WordPress 6.0+
The plugin is tested up to WordPress 6.6.
WooCommerce
Any recent WooCommerce version with standard payment gateway support.
PHP 7.4+
Minimum PHP version required by the plugin.
Crypto Checkout instance
A running self-hosted Crypto Checkout server with API access and a valid API key.
Installation
Download the plugin
Obtain the plugin ZIP from your Crypto Checkout instance or directly from the repository under
integrations/wordpress/. Do not extract the ZIP — WordPress accepts it as-is.Upload to WordPress
In your WordPress admin panel, go to Plugins → Add New Plugin → Upload Plugin. Choose the ZIP file, click Install Now, then Activate.
Configure the gateway
Navigate to WooCommerce → Settings → Payments → Crypto Checkout → Manage (or Settings). Fill in the following fields:
| Field | Value |
|---|---|
| API Base URL | Your Crypto Checkout instance URL, e.g. https://checkout.example.com |
| API Key | A key with sessions:write scope — ck_live_… for production, ck_test_… for test mode |
| Webhook Signing Secret | The whsec_… value from your webhook endpoint (see next step) |
| Webhook Endpoint ID | The UUID of your endpoint — enables Test send from the order admin screen |
Store the API key and webhook secret in the plugin settings fields marked as password inputs. They are never displayed in plaintext after saving.
Create a webhook endpoint
In your Crypto Checkout dashboard, go to Webhooks and create a new endpoint with the following values:
- URL:
https://your-store.com/wp-json/crypto-checkout/v1/webhook - Events: subscribe to all
session.*events (session.paid,session.expired,session.underpaid, etc.)
whsec_… secret immediately and paste it into the Webhook Signing Secret field in the WooCommerce settings. The secret is shown only once.Enable the gateway
Back in WooCommerce → Settings → Payments, toggle Crypto Checkout to Enabled and save.
How It Works
When a customer selects Crypto Checkout at checkout and clicks Place Order, the plugin calls your Crypto Checkout instance’s API to create a new checkout session for the exact WooCommerce order total. The customer is then redirected to the hosted checkout page, where a deposit address and ETH amount are displayed. Once payment is detected on-chain, your Crypto Checkout instance fires asession.paid webhook to the endpoint you configured. The plugin verifies the HMAC signature, looks up the matching WooCommerce order via the wc_order_id stored in session metadata, and automatically updates the order status.
Webhook Handling
The plugin registers a REST API route at:X-Webhook-Signature header before any order data is modified. Requests with an invalid or missing signature are rejected with a 401 response.
Order Status Mapping
| Crypto Checkout session status | WooCommerce order status |
|---|---|
pending | on-hold (set at session creation) |
paid | processing |
overpaid | processing |
underpaid | on-hold (pending review) |
expired | cancelled |
failed | failed |
The WooCommerce order is set to
on-hold immediately when the customer is redirected to checkout, before any blockchain activity occurs. This reserves stock while the payment is in flight.Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Orders stuck on on-hold | Webhook not reaching WordPress | Confirm the /wp-json/crypto-checkout/v1/webhook URL is publicly reachable and not blocked by a firewall or Cloudflare rule |
401 Unauthorized in delivery logs | Wrong webhook secret | Re-copy the whsec_… value from the Crypto Checkout dashboard and paste it into the plugin settings |
| Duplicate orders | Missing idempotency key | The plugin uses wc_order_<id>_v1 as the key — ensure you haven’t modified the PHP source |
| API call fails at checkout | Wrong API Base URL or key | Double-check the URL has no trailing slash and the key has sessions:write scope |