Skip to main content

Payment Flow

This page describes the complete payment experience from the customer's perspective, and how WordPress handles each step.

The flow​

Customer → WooCommerce checkout → Place Order
    → Plugin creates Coinsnap invoice
    → Customer redirected to Coinsnap payment page
    → Customer scans QR code with Bitcoin wallet
    → Payment confirmed
    → Webhook fires → WooCommerce order updated
    → Customer redirected to WooCommerce thank-you page

Step 1 — WooCommerce checkout​

The customer fills out the standard WooCommerce checkout form. Coinsnap appears as a payment option:

Bitcoin + Lightning (Coinsnap) Pay with Bitcoin via Lightning or Bitcoin

The payment option label and description are configurable in WooCommerce → Settings → Payments → Coinsnap → Manage.

Step 2 — Coinsnap payment page​

After clicking Place Order, the customer is redirected to the Coinsnap-hosted payment page. This page:

  • Shows the order amount in the store's fiat currency and the equivalent in Bitcoin
  • Displays a Lightning QR code (recommended — instant and fee-free)
  • Displays a Bitcoin QR code as a fallback
  • Shows a countdown timer (15-minute payment window)
  • Updates in real time when payment is detected

The customer scans the QR code with any Bitcoin or Lightning wallet (e.g. Phoenix, Muun, BlueWallet, Breez).

The payment page is hosted by Coinsnap at app.coinsnap.io. Your customer never enters payment details on your server.

Step 3 — Payment confirmation​

Lightning payment: Confirmed in 1–3 seconds. The page shows a success message immediately.

On-chain payment: The page shows "Payment detected" once the transaction is broadcast. Full confirmation arrives after 1 block (~10 minutes). The WooCommerce order is set to on-hold until confirmation.

Step 4 — Return to WordPress​

After payment is confirmed, the customer is redirected to the WooCommerce thank-you page (/checkout/order-received/). The plugin updates the order status based on the webhook event.

Important: The redirect alone does not confirm payment. The plugin uses the webhook (see Webhooks) to update the order status. If the webhook arrives before the customer is redirected, the thank-you page will already show the order as paid.

Invoice expiry​

If the customer doesn't pay within 15 minutes:

  • The Coinsnap payment page shows an expiry message
  • The customer can click to generate a new invoice (same WooCommerce order, new exchange rate)
  • The WooCommerce order remains open with status pending
  • When the new invoice is paid, the webhook fires and the order is updated

The plugin checks for an existing valid invoice before creating a new one (validInvoiceExists()). If the previous invoice is in Expired or Invalid state, a fresh invoice is created at the current exchange rate. The WooCommerce order ID remains the same.

Bitcoin discount​

If you have configured a Bitcoin discount in Coinsnap, the discount is applied automatically at checkout and shown to the customer on the payment page.

See Advanced Features → Bitcoin Discount for configuration details.