Accepting Bitcoin on your WooCommerce store with GoBTC Pay

This guide takes you from having no account to accepting your first Bitcoin payment. It should take about 20 minutes.

This guide covers version 1.1.4 of the plugin.

What you will need before you start

• Access to your WordPress admin panel, with WooCommerce already installed
• A phone with the GoBTC Pay app installed (needed once, to connect your receiving wallet)

You do not need a plugin file. The plugin is installed from inside WordPress.

Requirements

WooCommerce must be active. WordPress will not let you activate the plugin without it.

Part 1. Create your GoBTC Pay account

1. Register

Go to https://merchant.gobtcpay.com and create an account.

You will receive a verification code by email. Enter it to confirm your address and sign in.

You do not need to create a store or a point of sale for the plugin.

2. Connect your receiving wallet

This is where your Bitcoin payments will arrive. Without it, customers cannot place orders paid in Bitcoin, so do this before anything else.

In the merchant dashboard, open Settings → Receiving wallet.

You will see a QR code. Open the GoBTC Pay app on your phone and scan it. This links your wallet to your merchant account.

Once connected, the dashboard will show your wallet as linked.

Part 2. Install the plugin

3. Install and activate

In your WordPress admin panel, go to Plugins → Add New and search for GoBTC Pay.

The plugin is called GoBTC Pay for WooCommerce. Click Install Now, then Activate.

That is the whole installation. Nothing to download, nothing to upload.

4. Open the plugin settings

After activation, click Settings under the plugin name in the plugins list.

(If you have navigated away, you can also reach it via WooCommerce → Settings → Payments → GoBTC Pay → Manage.)

Leave API base URL as it is. On a fresh installation the default is already correct.

At the bottom of the page you will see Installation identifier, a read only value. You do not need to do anything with it. It is what lets GoBTC Pay tell your stores apart if you run more than one on the same account.

Keep this page open. You will come back to it twice in the next steps.

Part 3. Connect the plugin to your account

You will now create two secrets in the merchant dashboard and paste each one into the plugin. Both are shown only once, so paste each one immediately after creating it.

5. Create your secret API key

In the merchant dashboard, open Settings → API keys and click Create key. Give it any name you like, for example "WooCommerce".

Copy the key that appears. It starts with sk_live_.

Go back to the plugin settings page in WordPress and paste it into Secret API key.

6. Register your webhook address

On the same plugin settings page, find the Webhook URL line and copy the address shown there.

In the merchant dashboard, open Settings → Webhooks and click Add endpoint. Paste the address you just copied and create the endpoint.

Copy the signing secret that appears. It starts with whsec_.

Go back to the plugin settings page and paste it into Webhook signing secret.

7. Turn it on

On the plugin settings page, tick Enable GoBTC Pay and click Save changes.

Part 4. Check that it works

8. Test the connection

On the plugin settings page, click Send a test webhook.

While the test is running the button disappears and is replaced by a line asking you to reopen the page. That is expected.

Delivery takes up to 7 minutes. Reload the page: the Last webhook received line should show a recent timestamp.

If it does, your store and your GoBTC Pay account are talking to each other.

9. Place a test order

There is no test mode. The plugin has no sandbox and no test network. Every order you place goes through real Bitcoin on mainnet, and every test purchase costs you real money. The amounts can be small, but they are real. Plan your trial orders accordingly.

Buy something small in your own store and choose Bitcoin (GoBTC Pay) at checkout. You will be taken to a payment page showing a QR code and a Bitcoin address.

Pay it from any Bitcoin wallet, or scan the QR with the GoBTC Pay app.

The Bitcoin you pay arrives in the receiving wallet you connected in step 2, so on your own store you are paying yourself, less the network fee.

Keeping the plugin up to date

Updates arrive the same way as for any other plugin: WordPress tells you on the Plugins screen and under Dashboard → Updates, and you update with one click. You can also turn on automatic updates for it in the Plugins list.

We recommend updating when prompted. The changelog on the Development tab of the plugin's page in the WordPress plugin directory says what changed in each release; where an update needs anything from you, it says so there.

What happens after a customer pays

Ship when the order reaches Processing. That is the whole rule. The rest of this section explains what you will see on the way there, because it differs depending on how the customer paid.

If the customer pays in the GoBTC Pay app

Pending payment → Processing, with no waiting in between, or Completed for an order that needs no shipping.

This is the fast path. The customer confirms the payment in the app and the order is yours to fulfil immediately. GoBTC Pay carries everything that happens on the Bitcoin network afterwards, so you do not wait for confirmations and you do not need to check anything.

If the customer pays from an ordinary Bitcoin wallet

Pending payment → On hold → Processing (or Completed for an order that needs no shipping).

The order sits in On hold while the Bitcoin network confirms the transaction. This usually takes about 10 to 30 minutes, but it can take considerably longer when the Bitcoin network is congested. The order then moves to Processing on its own. Occasionally an order skips On hold entirely, which simply means the payment was already confirmed the first time it was seen.

What On hold really means

On hold does not mean the money is on its way. Two different situations put an order there and they look identical in your order list:

• the customer sent the payment and it is waiting for confirmation, or
• the payment window expired with no money at all, and the order is waiting out a grace period in case the customer pays late.

So treat On hold as "nothing to do yet", never as "about to be paid". Ship on Processing, not before.

Cancelled

The grace period ran out and no money arrived. By default the grace period is 12 hours and it can be changed in the plugin settings, so an order that is never paid takes roughly half a day to reach Cancelled, not an hour.

Cancelling also tells GoBTC Pay to cancel the payment, and in most cases that is the end of it. Occasionally the money is already on its way and the cancellation does not go through. The order then returns to Processing and carries a note saying it was cancelled and paid after all. Your stock count stays correct, because cancelling had returned the stock and the payment reduces it again. Your customer has already had a cancellation e-mail that is not retracted, so tell them the order is going ahead. Ship it like any other paid order.

Things worth knowing

There is a minimum order amount. GoBTC Pay does not create payments below the Bitcoin dust limit, so very small orders cannot be paid in Bitcoin. In practice it is a fraction of a dollar. The customer is told so at checkout and can choose another payment method.

Unpaid orders clean up after themselves. If a customer starts checkout and never sends the money, you do not have to do anything. The order moves from Pending payment to On hold when the payment window expires, waits out the grace period, and then goes to Cancelled on its own. See Cancelled for what happens next.

Your secrets are shown only once. If you lose the sk_live_ key or the whsec_ secret, you cannot retrieve them. Create a new one instead: in Settings → API keys or Settings → Webhooks, use Rotate. The old value stops working immediately, so update the plugin right after.

Never use a live secret key on a copy of your store. If you clone your shop to a staging or test site, the copy carries the same orders and the same payment identifiers, which means it is able to cancel a real customer's real payment.

Clearing the Secret API key field on the copy does not remove the key: an empty field means "keep the previous value". Only two things actually work. Either deactivate the plugin on the copy, or save a different, separate key over the live one.

Switching the payment method off is not the same as switching the plugin off. Unticking Enable GoBTC Pay stops new payments from being created, but work on existing ones continues: the plugin keeps polling for confirmations, keeps receiving webhooks and can still cancel payments. To stop the plugin completely, deactivate it on the Plugins screen.

Running several stores on one GoBTC Pay account is safe. Each installation sends a payment reference that includes its own identifier, so two of your stores can reach the same order number for the same amount without being given each other's payment.

If something is not working

The Bitcoin payment option does not appear at checkout. Four things hide it, and the first two are the common ones:

• Enable GoBTC Pay is not ticked.
• One of Secret API key, Webhook signing secret or API base URL is empty.
• Your receiving wallet is not connected in the merchant dashboard. Go to Settings → Receiving wallet and scan the QR code with the app.
• GoBTC Pay rejected your secret key. Create a new one in Settings → API keys and paste it into the plugin.

The last two are not things you set in the plugin. GoBTC Pay checks the secret key when you save the plugin settings, and an unconnected receiving wallet is detected the first time the plugin tries to create a payment. From then on the plugin hides the payment method rather than letting customers reach a checkout that cannot work. Checkout itself keeps working normally with your other payment methods.

The test webhook never arrives. The address registered in Settings → Webhooks must match the Webhook URL shown on the plugin settings page exactly. If your site address has changed since you registered it, register the new address and paste the new whsec_ secret into the plugin.

Orders stay in On hold for a long time. Remember that On hold covers two cases. If the customer did send the money, confirmation usually takes about 10 to 30 minutes, but it can take considerably longer when the Bitcoin network is congested; the order moves to Processing on its own once confirmed. If the customer never sent anything, the order sits in On hold for the grace period and then cancels itself. Either way you do not need to act, and you should not ship.

If a payment was sent and never confirms, contact GoBTC Pay support with the order number.

Some orders reach Processing instantly and others take half an hour. That is the difference between a customer paying in the GoBTC Pay app and a customer paying from an ordinary Bitcoin wallet. Both are fully paid orders and both are yours to ship. When the plugin moves an order to On hold, it adds an order note saying whether the payment was seen on the network or the payment window closed.

You are not seeing the plugin's warnings. The plugin reports problems as notices in wp-admin, and it only shows each one to the people who can act on it and on the screens where the action is possible. Warnings about the installation itself appear on Plugins and the Dashboard, and only to users who can activate plugins. Warnings about a store that is already running, such as a webhook channel that has gone quiet, appear on the WooCommerce screens, and only to users who can manage WooCommerce. A warning that your store cannot take any payments at all is shown everywhere in wp-admin.