> For the complete documentation index, see [llms.txt](https://cryptonly.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cryptonly.gitbook.io/docs/integration/cms-plugins/woocommerce.md).

# WooCommerce

**Cryptonly - Crypto Payment Gateway for WooCommerce** lets your store accept cryptocurrency payments through Cryptonly's secure hosted checkout.

Customers select Cryptonly at checkout, pay on the Cryptonly payment page, and return to your store. WooCommerce order statuses are updated automatically when Cryptonly sends signed `invoice.statusChanged` webhooks.

The plugin supports both classic WooCommerce checkout and WooCommerce Blocks.

***

#### How the payment flow works

```mermaid
sequenceDiagram
    participant Customer
    participant WooStore as WooCommerceStore
    participant Cryptonly
    Customer->>WooStore: Place order with Cryptonly
    WooStore->>Cryptonly: Create invoice
    Cryptonly-->>WooStore: paymentPageUrl
    WooStore-->>Customer: Redirect to hosted checkout
    Customer->>Cryptonly: Pay with crypto
    Cryptonly->>WooStore: invoice.statusChanged webhook
    WooStore-->>Customer: Order status updated
```

At a high level:

1. The customer places a WooCommerce order and chooses Cryptonly as the payment method.
2. The plugin creates a Cryptonly invoice server-side (your API key never reaches the browser).
3. The customer is redirected to the Cryptonly hosted payment page.
4. After payment, Cryptonly sends webhooks to your store.
5. The plugin verifies each webhook and updates the WooCommerce order status.

For more detail on invoices and statuses, see [Invoices](/docs/guides/invoices.md).

***

#### Requirements

Before installing the plugin, make sure you have:

| Requirement              | Details                                                        |
| ------------------------ | -------------------------------------------------------------- |
| WordPress                | 6.0 or higher                                                  |
| WooCommerce              | 7.1 or higher                                                  |
| PHP                      | 7.4 or higher                                                  |
| Cryptonly account        | [Cryptonly merchant account](https://merchant.cryptonly.net/)  |
| Supported store currency | Your WooCommerce store currency must be supported by Cryptonly |

{% hint style="info" %}
The plugin is compatible with WooCommerce HPOS (High-Performance Order Storage) and includes bundled translations for English, Spanish, German, and Russian.
{% endhint %}

***

#### Install the plugin

The plugin is available in the official WordPress plugin directory:

{% embed url="<https://wordpress.org/plugins/cryptonly-crypto-payment-gateway-for-woocommerce/>" %}

**Install from the WordPress admin (recommended)**

1. In WordPress, go to **Plugins → Add New**.
2. Search for **Cryptonly**.
3. Click **Install Now**, then **Activate**.

**Or install manually**

1. Download the plugin zip from the [WordPress.org plugin page](https://wordpress.org/plugins/cryptonly-crypto-payment-gateway-for-woocommerce/).
2. In WordPress, go to **Plugins → Add New → Upload Plugin** and upload the zip. Or, move the `cryptonly-crypto-payment-gateway-for-woocommerce` folder to `/wp-content/plugins/` on your server (via FTP, SFTP, or your hosting file manager) and activate it from the **Plugins** menu.

After activation, go to **WooCommerce → Settings → Payments → Cryptonly** and enable the payment method.

***

#### Configure the plugin

Open **WooCommerce → Settings → Payments → Cryptonly** and review each setting.

First enable the payment method, then complete the **Connection** settings, customize customer-facing text, and adjust **Advanced** options only if needed.

| Setting                       | Purpose                           |
| ----------------------------- | --------------------------------- |
| **Enable Cryptonly payments** | Turn the payment method on or off |

**Connection**

| Setting                 | Purpose                                                                                                                                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Key**             | Your Cryptonly account API key                                                                                                                                                                              |
| **Account ID**          | Cryptonly account UUID used for invoice creation                                                                                                                                                            |
| **Webhook Signing Key** | Used to verify incoming Cryptonly webhooks                                                                                                                                                                  |
| **Public site URL**     | Optional public HTTPS base URL for generated webhook and merchant return links (return / success / failed CTAs). Leave empty on public HTTPS stores; set it when the WordPress site URL is local or private |
| **Webhook URL**         | Read-only preview of the webhook endpoint sent with each invoice                                                                                                                                            |
| **Sandbox Mode**        | Use the Cryptonly sandbox API for test payments                                                                                                                                                             |

**Customization**

| Setting                   | Purpose                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| **Title**                 | Payment method name shown at checkout (default: Pay with Crypto)                         |
| **Description**           | Short text shown under the payment method at checkout                                    |
| **Instructions**          | Optional text on the thank-you page and in customer emails for pending or on-hold orders |
| **Resume payment button** | Button label that returns customers to the Cryptonly payment page                        |

**Advanced**

| Setting                | Purpose                                                                                                          |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Order ID Prefix**    | Prefix for Cryptonly `orderId` values (default: `WC-`). Must not end with a digit. Use a unique prefix per store |
| **Compatibility Mode** | Send only the final order total when line-item totals do not match because of checkout or pricing plugins        |
| **Debug Log**          | Write Cryptonly events to **WooCommerce → Status → Logs** (source: `cryptonly`)                                  |

**Webhook URL behavior**

The plugin sends a `webhookUrl` automatically on every invoice it creates. You do **not** need to configure a default invoice webhook in the Cryptonly dashboard for the standard WooCommerce flow.

The **Webhook URL** field in plugin settings is a preview for troubleshooting only. In production it must be a public HTTPS address, for example:

```
https://your-store.com/?wc-api=WC_Gateway_Cryptonly
```

### Merchant return URLs

On each invoice the plugin sends browser **“Return to merchant”** CTAs (not webhooks / not auto-redirects). Order status still updates via the HTTPS `webhookUrl`.

| Field        | WooCommerce URL            | Shown when Cryptonly invoice is         |
| ------------ | -------------------------- | --------------------------------------- |
| `returnUrl`  | Thank-you / order-received | `cancelled`, `expired`                  |
| `successUrl` | Thank-you / order-received | `paid`, `overpaid`                      |
| `failedUrl`  | Order-pay (retry payment)  | `failed`, `suspended`, `partially_paid` |

Cryptonly accepts any `http`/`https` URL for these fields (including `http://localhost:…` for local testing). See [Invoice statuses](/docs/guides/invoices/statuses.md) for the full status → URL map.

If your WordPress site URL is local or private (for example during staging), set **Public site URL** to your public HTTPS domain so Cryptonly can reach the webhook endpoint and rewrite merchant return URLs onto the correct store host.

For webhook signing details, see [Webhooks](/docs/integration/webhooks.md).

***

#### Test in sandbox before going live

1. Register at the [sandbox merchant panel](https://sandbox-merchant.cryptonly.net).
2. Copy your sandbox **API Key**, **Account ID**, and **Webhook Signing Key**.
3. In the plugin settings, enable **Sandbox Mode**.
4. Enter your sandbox credentials and save.
5. Place a test order and complete payment on the Cryptonly [sandbox payment page](/docs/guides/sandbox-environment.md) using testnet assets only, or use **Simulate payment** on the invoice in Cryptonly **Accounts → History** to settle it without sending testnet funds.
6. Confirm the WooCommerce order updates to **Completed**.

See the [Sandbox environment](/docs/guides/sandbox-environment.md) guide for supported test networks and safety notes, and [Testing your integration](/docs/guides/testing-your-integration.md) for more on the History and simulator tools.

{% hint style="warning" %}
Sandbox uses testnets only. Do not send mainnet funds to sandbox payment addresses.
{% endhint %}

***

#### Customer checkout experience

1. The customer adds products to the cart and goes to checkout.
2. They select the Cryptonly payment method and place the order.
3. WooCommerce creates the order and the plugin creates a Cryptonly invoice.
4. The customer is redirected to the Cryptonly hosted payment page.
5. After payment, the customer returns to your store thank-you page.

**If the customer abandons payment**

The WooCommerce order stays open while the Cryptonly invoice is still payable. The customer can return to the payment page from:

* the thank-you page
* order details
* customer emails
* customer orders list

***

#### How order statuses are updated

The plugin listens for `invoice.statusChanged` webhooks and maps Cryptonly invoice statuses to WooCommerce order statuses:

| Cryptonly invoice status  | WooCommerce order status |
| ------------------------- | ------------------------ |
| `created`                 | pending                  |
| `processing`, `suspended` | on-hold                  |
| `paid`, `overpaid`        | completed                |
| `partially_paid`          | on-hold                  |
| `expired`, `failed`       | failed                   |
| `cancelled`               | cancelled                |

Key behavior:

* Webhooks are the source of truth for payment status updates.
* The plugin verifies the `x-webhook-signature` header using your **Webhook Signing Key**.
* Once an order is paid or completed, later out-of-order webhooks will not downgrade it.
* The invoice (and its WooCommerce order) stays `pending` from checkout until an on-chain transaction is detected, then moves to **on-hold**; there is no separate "deposit address generated" webhook.

For the full invoice lifecycle, see [Invoice statuses](/docs/guides/invoices/statuses.md).

***

#### Go live checklist

Before accepting real payments:

* [ ] Disable **Sandbox Mode**
* [ ] Enter production **API Key**, **Account ID**, and **Webhook Signing Key**
* [ ] Confirm your store uses a public HTTPS URL
* [ ] Confirm the webhook preview in plugin settings shows `https://…`
* [ ] Confirm the **Webhook Signing Key** in the plugin matches **Settings → Security** in Cryptonly
* [ ] Place a small real test order
* [ ] Verify the order moves from pending/on-hold to completed after payment

***

#### Troubleshooting

**Cryptonly is not shown at checkout**

* Go to **WooCommerce → Settings → Payments** and make sure Cryptonly is enabled.
* Confirm **API Key**, **Account ID**, and **Webhook Signing Key** are filled in.
* For block checkout, hard-refresh the page after saving settings.

**“Unable to start Cryptonly payment”**

Common causes:

* Missing or invalid Cryptonly credentials
* Store currency is not supported by Cryptonly
* `webhookUrl` is not a valid public HTTPS URL (Cryptonly must reach it)
* `returnUrl` / `successUrl` / `failedUrl` are not valid `http`/`https` URLs (localhost is allowed for local testing)

If your WordPress site URL is local or private, set **Public site URL** to your public HTTPS domain for webhooks (or use a tunnel such as ngrok), and try again.

**Webhooks are not arriving**

* Confirm the webhook preview in plugin settings uses `https://…`, not `http://localhost`
* Confirm your store is reachable from the public internet
* Confirm the **Webhook Signing Key** in the plugin matches Cryptonly **Settings → Security**
* Enable **Debug Log** and check **WooCommerce → Status → Logs** (source: `cryptonly`)

**Order stays pending after payment**

* Check whether Cryptonly shows the webhook as delivered
* Verify the webhook signing key is correct (invalid signatures are rejected)
* Enable **Debug Log** and look for `Webhook received for event invoice.statusChanged`
* Confirm the WooCommerce order exists and matches the Cryptonly invoice

**Customer cannot resume payment**

* The Cryptonly invoice may have expired or been cancelled
* Ask the customer to place a new order if the invoice is no longer payable
* Customize the resume button label under **Resume payment button** if needed

**WooCommerce cancelled the order while payment was in progress**

Crypto payments can take time to confirm on-chain. If orders are cancelled too early:

* Increase **WooCommerce → Settings → Products → Inventory → Hold stock (minutes)**, or disable it
* The order stays `pending` until an on-chain transaction is detected (invoice moves to `processing`, mapped to **on-hold**)

***

#### Frequently asked questions

**Which cryptocurrencies are supported?**

Cryptonly supports Bitcoin, Ethereum, USDT, USDC, and many other cryptocurrencies. Available assets depend on your Cryptonly account and enabled networks.

**Does it work with WooCommerce Blocks checkout?**

Yes. The plugin supports both classic WooCommerce checkout and WooCommerce Blocks.

**Can I customize checkout text?**

Yes. In plugin settings you can change **Title**, **Description**, **Instructions**, and **Resume payment button**.

**Do I need to configure webhooks in the Cryptonly dashboard?**

No. The WooCommerce plugin sends the webhook URL automatically with each invoice. You only need to enter the **Webhook Signing Key** in the plugin so incoming webhooks can be verified.

**Can I run the store in another language?**

Yes. The plugin includes bundled translations for Spanish, German, and Russian. Set your site language in **Settings → General → Site Language**.

***

#### Related documentation

* [WordPress.org plugin page](https://wordpress.org/plugins/cryptonly-crypto-payment-gateway-for-woocommerce/)
* [Invoices](/docs/guides/invoices.md)
* [Webhooks](/docs/integration/webhooks.md)
* [Sandbox](/docs/guides/sandbox-environment.md)
* [Testing your integration](/docs/guides/testing-your-integration.md)

***

#### Support

For help with your Cryptonly merchant account, supported assets, credentials, or payment questions, contact us via email **<connect@cryptonly.net>**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cryptonly.gitbook.io/docs/integration/cms-plugins/woocommerce.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.