Accept Bitcoin in your WooCommerce store

How it works

1. 1The customer chooses GoBTC Pay at checkout.
2. 2They are redirected to the GoBTC Pay hosted checkout page and pay there.
3. 3The order status in WooCommerce updates automatically, through two independent channels: a signed webhook and polling. They overlap almost everywhere, so a single missed poll or a single undelivered webhook does not strand a paid order. They are not interchangeable, though: once an order's payment window and its grace period have both run out, polling for that order stops, and a payment that arrives after that reaches the store only as a webhook. That is why keeping the webhook endpoint reachable is not optional.

Two ways to pay

Orders on hold and late payments

Every payment has a payment window, and while it is open the customer pays as usual. An order is usually On hold for one of two reasons:

• It was paid from an ordinary Bitcoin wallet and is waiting for network confirmation, as described above.
• The payment window closed before the customer paid. The order is held rather than cancelled, and the plugin keeps watching it for a grace period — 12 hours by default, and configurable. A payment that arrives inside the grace period still pays the order.

If nothing arrives before the grace period ends, the order is cancelled. WooCommerce then restores the stock and sends its own cancellation e-mail, and neither is undone if the money turns up later.

What you need

• WordPress 6.0 or newer, with WooCommerce 8.0 or newer
• PHP 8.1 or newer
• A store served over https
• A GoBTC Pay merchant account with an API key

Works with both the classic checkout and the Cart and Checkout Blocks. Without https the customer is not sent back to your store automatically after paying; payment status still syncs and orders are still completed.

Setting it up

1. 1Install and activate the plugin. WooCommerce must be installed and active.
2. 2Open WooCommerce settings, go to Payments and select GoBTC Pay.
3. 3Enable the payment method and fill in all three required fields: the secret API key from your GoBTC Pay merchant cabinet, the webhook signing secret of the webhook endpoint you create there, and the API base URL. The plugin checks the key when you save and tells you if it is not accepted; if it cannot reach the platform, the key is saved unverified and re-checked in the background.
4. 4Copy the webhook URL shown on the settings page and register it as a webhook endpoint in your GoBTC Pay merchant cabinet.
5. 5Send a test webhook from the same settings screen to confirm that GoBTC Pay can reach your store.

The plugin folder is gobtc-pay-for-woocommerce, and a release archive is named gobtc-pay-for-woocommerce-<version>.zip.

Installed version 1.0.0 by hand from a release zip? Version 1.1.0 renamed the folder, so the old one stays behind as a separate, still-active plugin. Deactivate and delete it — the new copy will tell you if you forget. Your settings and existing orders are unaffected.

Copying your store to a staging or test site

Never let a copy run with the live secret key. Before the copy is first opened, not after, do one of two things on it: deactivate the plugin, or save a separate key over the live one. Emptying the secret API key field does not remove the stored key — a blank field means “keep the current value” — and turning the payment method off does not stop the plugin talking to GoBTC Pay either.

The key is not read-only. A copy carries the same orders and the same payment identifiers, and the plugin asks GoBTC Pay to cancel a payment whenever its order is cancelled or its total has changed. Cancelling an order on the copy, or letting it expire there, cancels the real payment of a real customer — and nothing on the copy looks wrong while this happens.

Once the key is dealt with, delete the plugin's site identifier on the copy: the gobtc_pay_site_id option. The plugin creates a new one by itself. The current value is shown as “Installation identifier” at the bottom of the payment method's settings screen, which is how you tell the copy from the original once you have done this.