GoBTC Pay for WooCommerce

Description

GoBTC Pay for WooCommerce adds Bitcoin as a payment method to your store. The
customer is sent to a hosted checkout operated by GoBTC Pay, pays there, and —
if your store is served over https — comes back to its usual order-received
page. Your store never handles
private keys, wallet software or on-chain transactions.

The plugin keeps the order in step with the payment through two independent
channels: it polls the payment status on a schedule, and it accepts signed
webhook deliveries from GoBTC Pay. The two 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. Keeping the webhook
endpoint reachable is therefore not optional.

Two payment routes, and they do not behave the same

This is the part worth understanding before you install, because it decides
when your goods are released.

Paid from a wallet inside the GoBTC Pay ecosystem (instant). The payment
reports as paid in one step. The order is marked paid and moves straight to a
state that allows fulfilment — Processing, or Completed for an order that needs
no shipping. There is no waiting period. The plugin keeps polling in the
background until the on-chain settlement time appears, but the order is already
paid and the merchant is not asked to wait for it.

Paid from an ordinary Bitcoin wallet (external). The transfer is first seen
in the mempool, and the order is held On hold while it waits for network
confirmation. Only once the payment is confirmed on-chain does the order move
to a state that allows fulfilment. This usually takes about 10 to 30 minutes,
but it can take considerably longer when the Bitcoin network is congested.
Confirmation time is a property of the network: neither the plugin nor your
store can influence it.

Both routes end with a paid order. The difference is the path the order takes
and how long it takes to get there, so an On-hold order from an external
payment is a normal, expected state and not a fault.

Late payments

If the payment window closes before the customer pays, the order is held rather
than cancelled, and the plugin keeps watching it for a configurable grace period
(12 hours by default). A payment that arrives inside that window still pays the
order.

What happens after the grace period. If nothing arrives before it ends, the
order is cancelled: WooCommerce restores the stock and sends its own
cancellation e-mail. In most cases that is the end of it, because the payment
is cancelled on the GoBTC Pay side at the same time. Occasionally the money is
already on its way and that cancellation does not go through. The payment is
then applied after all: the order returns to Processing, the stock is reduced
again, which leaves the count correct because cancelling had returned it, and
the order gets a note saying it was cancelled and paid after all. The
cancellation e-mail your customer has already received is not retracted, so
tell them the order is going ahead. Treat it as any other paid order and ship
it.

What the plugin does not do

• It does not process refunds. Refunds are handled outside the plugin.
• It does not support subscriptions or pre-orders.
• It does not store card details or private keys, because it never sees any.

External service disclosure

This plugin is a client for a third-party service and does not work without it.

See “External service” below for the service, its endpoints and its legal
terms. This subsection covers the one thing that section does not: exactly what
leaves your store, and the one configuration that can cost you real money.

Endpoints contacted by your server: the API base URL you configure in the
plugin settings — https://api.gobtcpay.com/public/api/v1.2 for production, or
https://pay.dev.gobtcpay.com/public/api/v1.2 for the separate non-production
contour operated by GoBTC Pay. That contour runs on Bitcoin mainnet: payments
made against it move real BTC. It is not a sandbox and there is no test
network behind it.

What your server sends to GoBTC Pay:

• When an order is placed: the order total, the order currency, and a reference
  string built from a random identifier of this installation, the WooCommerce
  order ID, currency and total (for example
  wc-a1b2c3d4-order-1234-USD-4999). The installation identifier is a random
  value and is not derived from your site address. No customer name, e-mail
  address, postal address or cart contents are sent, and the customer’s IP
  address is not sent.
• Afterwards, to follow the payment: the identifier of the payment that GoBTC
  Pay returned.
• When an order is cancelled or its total changes: the identifier of the
  payment that is no longer valid.
• To verify your credentials: your secret API key, so the platform can confirm
  it is usable. This runs when you save the settings, and is retried in the
  background — for up to about a day — if the platform could not be reached.
• When you press the webhook test button: a request to deliver a test webhook to
  your store.

What GoBTC Pay sends back to your server: the payment’s status, amount,
currency, identifiers, timestamps and, where present, its on-chain transactions.
Webhook deliveries are signed and their signature is verified before anything is
applied to an order.

What the customer’s browser sends: the customer is redirected to the GoBTC
Pay hosted checkout, so their browser contacts GoBTC Pay directly and that
service sees whatever a website normally sees about a visitor. The redirect
carries the two addresses the customer is returned to on your store — the
order-received page and the pay-again page.

Terms of service: https://gobtcpay.com/terms
Privacy policy: https://gobtcpay.com/privacy-policy

External service

This plugin connects your WooCommerce store to GoBTC Pay, a Bitcoin payment
service operated by GoMining. The plugin does not process payments itself:
it creates a payment through the GoBTC Pay merchant API and redirects the
customer to the GoBTC Pay hosted checkout page to complete it.

The service is contacted in the following cases:

• when a customer places an order and selects GoBTC Pay as the payment
  method, to create the payment and obtain the checkout URL
• periodically after that, to read the current payment status until the
  payment reaches a final state
• when the plugin validates your API key, sends a test webhook, or cancels
  a payment from the WooCommerce admin

The customer is redirected to the hosted checkout page at
https://pay.gobtcpay.com. Whether they are sent back afterwards depends on your
store: a return address is only handed to the hosted checkout when the store is
served over https, and without one the customer stays on the checkout page after
paying — see “Installation” for the requirement. The payment itself is
unaffected either way: the plugin reads the payment status from the service on
its own schedule, so an order still reaches its final state whether or not the
customer comes back.

The data sent to the service for each payment is the order amount, the
order currency, and an order reference generated by the plugin. Your secret
API key is sent as an authorization header and is never exposed to the
customer’s browser.

Service provider: GoMining (GoBTC Pay)
Merchant API: the GoBTC Pay merchant API, at the base URL configured in the
plugin settings
Hosted checkout: https://pay.gobtcpay.com
Terms of Service: https://gobtcpay.com/terms
Privacy Policy: https://gobtcpay.com/privacy-policy