Crypto payment plugins for WooCommerce and Shopify: checkout flow, order states and refunds
How a crypto payment plugin works on WooCommerce and Shopify: checkout flow, order states during confirmations, refunds, Shopify's partner review and costs.
BitPolaris Engineering
English original
A crypto payment plugin for WooCommerce or Shopify does three things: it creates an invoice on a payment gateway when the buyer chooses crypto, it sends the buyer to a hosted checkout to pay, and it updates the shop order when the gateway reports the payment. Everything else (deposit addresses, chain watching, confirmations, wallets, payouts and refunds) happens in the gateway behind it. That split is why the two platforms feel so different to build for: WooCommerce lets anyone publish a gateway plugin and leaves the order logic to you; Shopify only lets approved payments partners in and sets the rules.
This guide is written for payment companies and PSPs that want to offer crypto checkout to their merchants under their own brand. It covers the checkout flow on each platform, the order states that cause most support tickets, refunds, what Shopify asks of a payments partner and what it costs. Platform rules were read on the WooCommerce and Shopify developer documentation on 16 November 2026 and are listed under Sources.
The checkout flow, step by step
The flow is the same on both platforms; only the names change.
- Buyer chooses crypto at checkout. The plugin calls the gateway: amount, price currency, the order ID and a callback URL. In our API that is one
POST /v1/invoicescall that returns a checkout URL and an expiry. - Redirect to the hosted checkout. The buyer picks a coin and network, sees the amount, address and QR code, and pays from a wallet or an exchange account.
- Payment detected. The gateway sees the transaction on chain, before final confirmation. The shop order should show “payment in progress”, not “paid” and not “cancelled”.
- Payment confirmed. After the confirmation depth for that network, the gateway sends a signed event and the plugin marks the order paid, which releases stock and fulfilment.
- Exceptions. Underpayment, overpayment, payment after expiry, wrong network. Each needs a defined order state and a merchant notification.
Steps 3 and 5 are where crypto differs from cards. A card authorisation answers in seconds; a crypto payment can take minutes to confirm, and a buyer paying from an exchange account may send less than asked (the exchange deducts its withdrawal fee) or send it after the invoice expired. How to build a USDT payment gateway covers the gateway side of each exception; this article covers what the plugin does with them.
WooCommerce: open platform, your order logic
A WooCommerce gateway is a PHP class that extends WC_Payment_Gateway and is registered through the woocommerce_payment_gateways filter. Its process_payment() method returns a redirect URL, which for a crypto plugin is the hosted checkout. Callbacks from the gateway arrive through a WC-API endpoint, the hook WooCommerce recommends for payment notifications.
Three WooCommerce details shape a crypto plugin:
- The hold-stock timer. WooCommerce’s documentation warns that orders in “Pending payment” are cancelled after the hold-stock time, 60 minutes by default. A crypto payment detected at minute 55 and confirmed at minute 70 lands on a cancelled order. The plugin should move the order to “On hold” when the payment is detected (WooCommerce’s status for payments that need verification) and only call
payment_complete()on confirmation, which lets WooCommerce move it to Processing and handle stock. Our plugin moves the order to Processing on thepayment.confirmedevent. - Late payments. If the invoice expires and the order is cancelled, a payment that arrives later still has to go somewhere. Decide whether the plugin reopens the order, flags it for the merchant or leaves the funds on the merchant’s gateway balance for a manual decision. Silence is the worst choice: the buyer has paid and the shop shows nothing.
- Refund button. WooCommerce shows its automatic refund button only for gateways that declare
refundsin theirsupportsarray and implementprocess_refund();can_refund_order()can hide it per order. Many crypto plugins do not declare it, and merchants then refund outside the shop, which breaks their accounting.
Block-based checkout is a separate integration: WooCommerce’s payment gateway documentation covers the classic checkout page and points to a separate payment method integration guide for the Checkout block. Ask any plugin vendor which of the two it supports and test the one your merchants use.
Shopify: closed platform, Shopify’s rules
On Shopify a payment method is a payments extension built on the Payments Apps API, and Shopify lists cryptocurrency among the supported payment methods. The offsite extension type fits a hosted crypto checkout: it “allows merchants to redirect their buyers to an app-hosted website to complete the payment process”.
The access rules matter more than the API:
- Invitation only. Shopify states that its payments platform “is invitation only while we continue to build out our Payments Apps API”. A PSP applies to become a payments partner; applying does not guarantee acceptance, and Shopify gives no timeline.
- Two reviews. First the payments partner application, then the payments app review. An approved app starts in a Hidden state: merchants cannot find it in the Shopify admin but can install it from an installation link you send them.
- Revenue share. Every payments partner signs a revenue share agreement, calculated on total payment volume processed by the app for all Shopify merchants; Shopify waives invoicing until the first month in which that volume exceeds $150,000.
- Operating requirements. The extension must settle transactions within five days, be available 24/7 at least 99.95% of the time, respond to outages within two hours, use only the Payments Apps API and mandatory webhooks, implement idempotency and retries, and use mutual TLS for requests Shopify sends. Merchants must be able to terminate with seven days’ notice, and pricing must be transparent without teaser rates.
- Features. Merchants must be able to “charge, refund, and process test transactions”.
For crypto, the useful part of the API is the pending state. When the buyer has paid but the transaction is not yet confirmed, the app calls paymentSessionPending with a reason and an expiry, which Shopify recommends keeping within three days, sends the buyer back to the store, and later finalises the session with paymentSessionResolve or paymentSessionReject. Refunds arrive as refund sessions that the app resolves or rejects.
What this means for a PSP: the Shopify plugin is a partnership and an operations commitment, not a software purchase. Software can be ready in weeks; whether and when Shopify approves your app is Shopify’s decision, and the 99.95% and two-hour commitments apply to your gateway, not only the app.
Refunds: the part most plugins skip
A card refund reverses a transaction. A crypto refund is a new outgoing payment, and each one raises four questions the plugin has to pass to the gateway:
| Question | Why it matters | What to decide |
|---|---|---|
| Where to? | The sending address is often an exchange’s hot wallet, not the buyer’s | Ask the buyer for a refund address on the same network and screen it |
| How much? | The coin price may have moved since payment | Refund in the price currency at today’s rate, or the coin amount received |
| Who pays the fee? | Network fees vary by chain and over time | Usually deducted from the refund; state it in the merchant terms |
| Who approves? | A refund is a payout from a balance | The same approvals as any payout |
In our gateway a refund is a payout: it goes only to an approved address and is confirmed with 2FA, from the merchant’s balance. On Shopify, a refund request arrives as a refund session that the app resolves once the refund is sent; how long a session may stay open while the buyer supplies an address is a question to settle with Shopify during review. On WooCommerce, the plugin decides whether to collect the address itself or send the buyer a link. Either way, write down the rule before launch, because merchants will ask in the first week.
What a PSP needs before offering plugins
- A gateway that handles the exceptions. Detected, confirmed, partial and expired events, signed and retried; plugins are only as good as the events behind them. Ours sends
payment.detected,payment.confirmed,payment.partial,payment.expiredandpayout.sent, HMAC-SHA256 signed with a five-minute replay window and retried with backoff for 24 hours. - Your own accounts. The WooCommerce plugin is published under your name, the Shopify app under your partner account; listings, reviews and support contacts are yours.
- Settlement choice for merchants. Decide whether merchants settle in the coin paid, in a stablecoin or in fiat; USDT vs USDC for merchant payments compares the two, and an auto-convert option settles other coins into one of them.
- Merchant onboarding and KYB where your licence requires it, plus a clear answer to who the merchant contracts with.
- Support for the first month. Expect early tickets about orders that look unpaid and about refunds. Stablecoin payment gateways for PSPs covers fees, settlement and compliance on the gateway side.
What it costs with BitPolaris
Our prices are public in EUR on the pricing page:
| Item | Cloud | Self-hosted | Source code |
|---|---|---|---|
| Payments block | €2,100 setup + €410 a month | €7,700 + €1,540 a year updates | €20,300 |
| Shop plugins (WooCommerce, Shopify, Magento, OpenCart) | €2,100 one-time | €2,100 one-time | €2,100 one-time |
| Auto-convert to stablecoin | €100 a month | €2,100 | €2,100 |
| Extra gateway chain (BSC, SOL, AVAX, XRP…) | €980 each, one-time | €980 each | €980 each |
The plugin fee covers rebranding and publishing under your accounts. It does not cover Shopify’s partner approval or revenue share, which are between you and Shopify, or WordPress.org review if you list the WooCommerce plugin there. On cloud, the one we call white-label, we run the gateway on dedicated EU servers; self-hosted, your team does. Magento and OpenCart plugins are delivered on request with the same event model.
Crypto payment plugin FAQ
How does a crypto payment plugin for WooCommerce work?
It adds a payment method that creates an invoice on a crypto payment gateway, redirects the buyer to a hosted checkout and updates the order when the gateway sends a signed event. A well-built plugin moves the order to On hold when the payment is detected, so WooCommerce’s hold-stock timer does not cancel it, and to Processing when it is confirmed.
Can I add crypto payments to Shopify?
Shopify lists cryptocurrency among the payment methods its payments extensions support, but its payments platform is invitation only. A payment company has to be accepted as a payments partner, sign a revenue share agreement and pass app review; merchants then install the approved app. A merchant cannot add an unapproved crypto gateway on its own.
How do refunds work with crypto payments?
A refund is a new outgoing transfer, not a reversal. The merchant or the gateway needs a refund address on the same network, a rule for the amount (price currency at today’s rate or the coin amount received), a rule for the network fee and an approval. WooCommerce shows its refund button only if the gateway declares refund support; Shopify expects payments apps to support refunds.
What happens if a customer underpays or pays late?
Underpayments usually come from an exchange’s withdrawal fee. The gateway should detect the shortfall, send the buyer a top-up link and tell the merchant; the order stays on hold. Late payments after the invoice expired should be flagged to the merchant and not lost; whether the order reopens is the merchant’s rule.
How long does it take to launch crypto payment plugins?
Our Payments block goes live in about two weeks; the WooCommerce plugin can be published when the gateway is live. The Shopify app depends on Shopify accepting you as a payments partner and approving the app, for which Shopify gives no timeline.
Sources
All read on 16 November 2026.
- WooCommerce, Payment gateway API (gateway class, order statuses, hold-stock time, WC-API callbacks)
- WooCommerce code reference, WC_Payment_Gateway (
supports,process_refund(),can_refund_order()) - Shopify, Extensions for payments (extension types, supported payment methods)
- Shopify, Requirements for payments extensions (settlement, revenue share, availability, features)
- Shopify, Get approved for payments (invitation only, reviews, app states)
- Shopify Payments Apps API, paymentSessionPending and refundSessionResolve
BitPolaris licenses the payment gateway a PSP needs to offer crypto checkout under its own brand: hosted checkout, signed webhooks, a merchant panel, an operator console and WooCommerce and Shopify plugins published under your accounts. Prices are public.