The BchainPay plugin adds a "Pay with Crypto" gateway to WooCommerce.
Customers can pay with ETH, USDT, USDC, DAI, SOL, TRX, BNB, and BUSD across
four networks directly from your checkout page — no code required.
In your WordPress admin, go to Plugins → Add New → Upload Plugin.
Upload the ZIP file and click Install Now.
Click Activate Plugin.
The gateway now appears under WooCommerce → Settings → Payments.
Configuration
Navigate to WooCommerce → Settings → Payments → BchainPay to configure the
plugin.
Required settings
Setting
Description
API Key
Your BchainPay API key. Starts with pk_live_ (production) or pk_test_ (sandbox).
Webhook Secret
The signing secret used to verify incoming webhooks. Copy this from the Dashboard → Webhooks page.
Optional settings
Setting
Default
Description
API URL
https://api.bchainpay.com
Override only if you use a custom API proxy or the sandbox URL.
Default Network
ethereum
The blockchain network used when the customer doesn't choose one.
Default Token
USDT
The token used when the customer doesn't choose one.
Allow Token Choice
yes
Show network + token dropdowns on the checkout page so the customer can pick how they pay.
Payment Timeout
30 (minutes)
How long the customer has to send funds before the payment expires. Drives the countdown timer.
Auto Confirm
yes
Automatically confirm the payment intent after address generation. Recommended for most stores.
Settlement Currency
(blank)
Optional settlement currency (e.g. USD). Leave blank to use the store currency.
Payment flow
Here's what happens from the customer's perspective:
Checkout — The customer selects "Pay with Crypto" as their payment
method.
Choose crypto — If Allow Token Choice is enabled, two dropdowns appear:
Network (Ethereum, BNB Chain, Solana, Tron) and Token (varies by
network). Otherwise the store defaults are used.
Place order — The plugin creates a payment intent via the BchainPay API,
generates a deposit address, and (if Auto Confirm is on) confirms the
intent automatically.
Payment page — The customer is redirected to a payment instructions page
showing:
The blockchain address to send funds to
A scannable QR code
A countdown timer (persists across page reloads)
Send funds — The customer sends the exact amount from their wallet.
Confirmation — The page polls for status updates every 12 seconds.
Once the BchainPay webhook confirms the payment, the order moves to
Processing (or Completed) and the customer sees a success message.
Webhook setup
The plugin exposes a dedicated webhook endpoint. You must register it in
the BchainPay Dashboard for payments to be confirmed automatically.
Select the events you want to receive. At minimum subscribe to
payment_intent.completed and payment_intent.expired. For the
richest order lifecycle, subscribe to all payment_intent.* events — the
plugin also handles payment_detected, confirmed, and failed.
Copy the Signing Secret shown after saving and paste it into the
plugin's Webhook Secret field in WooCommerce.
How verification works
Every incoming webhook includes an X-Webhook-Signature HMAC-SHA256 header. The plugin
verifies this against your webhook secret and rejects any request with an
invalid or missing signature. Events are also deduplicated by event ID, so
replayed webhooks are safely ignored.
Supported networks and tokens
Network
Tokens
Ethereum
ETH, USDT, USDC, DAI
BNB Chain
BNB, USDT, USDC, BUSD
Solana
SOL, USDT, USDC
Tron
TRX, USDT, USDC
When Allow Token Choice is enabled, the token dropdown updates automatically
based on the selected network (cascading dropdowns).
Order metadata
The plugin stores the following metadata on each WooCommerce order for
reference and debugging:
Meta key
Value
_bchainpay_intent_id
BchainPay payment intent ID
_bchainpay_address
Blockchain deposit address
_bchainpay_network
Network used (e.g. ethereum)
_bchainpay_token
Token used (e.g. USDT)
_bchainpay_amount_cents
Amount in cents (fiat)
_bchainpay_currency
Store currency (ISO-4217)
_bchainpay_status
Current intent status
_bchainpay_expires_at
Expiry as ISO 8601 timestamp
_bchainpay_crypto_amount
Crypto amount in smallest unit (e.g. lamports, wei)
_bchainpay_crypto_amount_decimal
Human-readable crypto amount (e.g. 0.042)
_bchainpay_token_price_cents
Token price in USD cents at time of order
You can view these in the WooCommerce order detail screen under
Custom Fields or query them with get_post_meta().
Troubleshooting
"Invalid API key" error at checkout
Confirm your key in WooCommerce → Settings → Payments → BchainPay.
Production keys start with pk_live_, sandbox keys with pk_test_.
Make sure there are no trailing spaces.
Webhook not received / order stuck on "On Hold"
Verify the webhook URL is correct and publicly reachable:
Confirm the Webhook Secret in the plugin matches the one in the
Dashboard.
If you use a security plugin (Wordfence, Sucuri, etc.), make sure it isn't
blocking POST requests to the REST API.
Payment timer expires too quickly
Increase the Payment Timeout in plugin settings. 30 minutes is the default;
60 minutes is a safer choice for customers who need to transfer from an
exchange.
Cascading dropdowns don't appear
Make sure Allow Token Choice is set to Yes.
Clear any page cache or CDN cache that may be serving a stale checkout page.
Check the browser console for JavaScript errors — a conflicting theme or
plugin may be interfering.
Duplicate order notes / double status changes
The plugin deduplicates webhook events by event ID. If you see duplicates,
check whether another integration (e.g. a custom webhook consumer) is also
processing BchainPay events for the same order.
