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

At a high level:

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

For more detail on invoices and statuses, see Invoices.

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
Supported store currency	Your WooCommerce store currency must be supported by Cryptonly

Install the plugin

The plugin is available in the official WordPress plugin directory:

WordPress admin
Manual

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

Download the plugin zip from the WordPress.org plugin page.
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	Cryptonly API key. The key selects the account. See required scopes
Webhook Signing Key	Signing key from that account’s Security settings. 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

API key scopes

Create the key on the account’s Security settings and enable only these scopes:

Scope	Used for
`invoices.create`	Create the invoice at checkout (`POST /invoice`)
`invoices.list`	Load an existing invoice when create returns a duplicate `orderId` (`GET /invoice`)
`invoices.cancel`	Cancel the invoice when the WooCommerce order is cancelled (`POST /invoice/cancel`)
`currencies.list`	Check that the store currency is supported (`GET /currencies/fiat`)

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 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.

Test in sandbox before going live

Register at the sandbox merchant panel.
Copy your sandbox API Key and Webhook Signing Key from the account Security settings.
In the plugin settings, enable Sandbox Mode.
Enter your sandbox credentials and save.
Place a test order and complete payment on the Cryptonly sandbox payment page using testnet assets only, or use Simulate payment on the invoice in Cryptonly Accounts → History to settle it without sending testnet funds.
Confirm the WooCommerce order updates to Completed.

See the Sandbox environment guide for supported test networks and safety notes, and Testing your integration for more on the History and simulator tools.

Customer checkout experience

The customer adds products to the cart and goes to checkout.
They select the Cryptonly payment method and place the order.
WooCommerce creates the order and the plugin creates a Cryptonly invoice.
The customer is redirected to the Cryptonly hosted payment page.
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.

Go live checklist

Before accepting real payments:

Disable Sandbox Mode
Enter production API Key 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 the account Security settings 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 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 the account’s Accounts → Settings → Security page
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.

WordPress.org plugin page

InvoicesHow checkout payments work

WebhooksVerification and payload details

Testing your integrationHistory and simulated invoice payments

Support

For help with your Cryptonly merchant account, supported assets, credentials, or payment questions, contact us via email [email protected].