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:
WordPress
6.0 or higher
WooCommerce
7.1 or higher
PHP
7.4 or higher
Cryptonly account
Supported store currency
Your WooCommerce store currency must be supported by Cryptonly
The plugin is compatible with WooCommerce HPOS (High-Performance Order Storage) and includes bundled translations for English, Spanish, German, and Russian.
Install the plugin
The plugin is available in the official WordPress plugin directory:
Install from the WordPress admin (recommended)
In WordPress, go to Plugins → Add New.
Search for Cryptonly.
Click Install Now, then Activate.
Or install manually
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-woocommercefolder 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.
Enable Cryptonly payments
Turn the payment method on or off
Connection
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
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
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:
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.
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, Account ID, and Webhook Signing Key.
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.
Sandbox uses testnets only. Do not send mainnet funds to sandbox payment addresses.
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:
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-signatureheader 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
pendingfrom 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:
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
webhookUrlis not a valid public HTTPS URL (Cryptonly must reach it)returnUrl/successUrl/failedUrlare not validhttp/httpsURLs (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://…, nothttp://localhostConfirm 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.statusChangedConfirm 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
pendinguntil an on-chain transaction is detected (invoice moves toprocessing, 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
Support
For help with your Cryptonly merchant account, supported assets, credentials, or payment questions, contact us via email connect@cryptonly.net.
Last updated