Prerequisites
- WordPress + WooCommerce installed and working checkout for fiat.
- Chosen Bitcoin gateway (hosted or self‑hosted) with API keys.
- Webhook endpoint reachable over HTTPS.
1) Install the gateway
In Plugins → Add New, install your gateway plugin and click Activate.
Go to WooCommerce → Settings → Payments and enable the gateway.
2) Configure API keys & pricing
Paste API keys (use Test keys first). Store secrets in wp‑config when possible.
Set pricing to fiat‑denominated with live FX; optionally display sats on the order page.
Add the webhook URL and secret; enable HMAC signatures and retries.
3) Customize checkout
- Label method as “Pay with Bitcoin (On‑chain or Lightning)”.
- Redirect to an invoice page with countdown and refresh on expiry.
- Show order id and contact info for support.
4) Verify payments & update orders
- Upon webhook, verify HMAC and confirm status with a secondary read.
- Mark Woo order to Processing (or Completed for digital goods) only after verified paid.
- Store the txid/payment hash and a receipt URL for customers.
5) Refunds & partials
- Collect return address securely; avoid storing PII.
- Support top‑ups for under‑pays or refund the difference for over‑pays.
Testing checklist
- Test on‑chain and Lightning payments with tiny amounts.
- Expire an invoice and ensure it refreshes properly.
- Simulate webhook retries and ensure idempotency.
- Verify receipt shows order id + proof link.
Troubleshooting
- No webhook received → check firewall, HTTPS, and plugin logs.
- Order stuck in “Pending” → confirm you’re verifying + secondary read.
- Amounts off → check FX source and rounding; always store both fiat and sats.
Next step: For custom apps, see Integrate invoices via API. For observability, add Bitcoin Flux to view invoice lifecycle and webhook delivery.