English
German
Spanish
French
Turkish
Back to Guides
Integrating Cryptocurrency Payments: A 2026 Playbook for E-commerce and SaaS
Integrating cryptocurrency payments in 2026 is no longer a custom engineering project. For most merchants it is a plug-in install or a four-endpoint API integration. The hard part is treasury, reconciliation, and compliance, not the wire-up.
This playbook covers the three realistic integration paths (hosted checkout, plug-in, direct API), the webhook and refund flows you need to model, the data you must capture for accounting, and the mistakes that kill most first-time rollouts. Written for the engineer or PM responsible for making it work, not the vendor selling it.
Boost Your Business by Accepting Crypto Payments
What Crypto Payment Integration Actually Means
Integrating cryptocurrency payments means wiring your checkout to a processor that can accept digital assets, confirm the transaction on-chain, and hand your business the proceeds (in fiat or stablecoin) with enough metadata for finance to reconcile it. The customer sees one extra payment button. Your team sees a new ledger entry in the same format as card and ACH transactions.
Under the hood, the integration does four things. It creates an invoice on your processor, displays a token amount and address to the buyer, watches the blockchain for confirmations, then signals completion back to your order system via webhook. Everything else is operational: tax lines, refunds, customer service, accounting export.
Typical fee range
0.5% - 1%
Versus 2.9% + $0.30 for cards. The spread compounds fast at scale.
Shortest integration path
Hours
Shopify, WooCommerce, and Magento plug-ins can ship in a single afternoon.
API endpoints you need
4
Create invoice, check status, handle webhook, issue refund. Everything else is optional.
Three Integration Paths
Every crypto integration belongs to one of three patterns. Pick the one that fits your engineering capacity and how much control you need over the checkout.
Hosted checkout
A redirect or modal pointed at the processor's hosted page. Fastest to launch. Almost no engineering.
- Ship in 1 to 2 days
- Zero PCI/security scope on crypto
- Limited UX control
Platform plug-in
Install the processor's official app from the Shopify App Store, WooCommerce marketplace, or Magento Marketplace. Wire API keys, pick assets, go live.
- Install in an afternoon
- Native checkout UX
- Upgradable with the platform
Direct API
Call the processor's REST API from your own backend. Full control, custom UX, fits any bespoke stack.
- 1 to 3 weeks of dev work
- Total UX and data control
- You own the uptime surface
Shopify Integration Step by Step
Shopify is the fastest path for most merchants. The platform does not yet allow crypto as a native payment method on all plans, so integrations run as checkout apps that present a "Pay with Crypto" flow.
Install the app
From the Shopify App Store. Grant the standard scopes (orders read/write, checkout, customers).
Connect your processor account
Paste API key and secret. Pick the assets and chains you want to accept.
Pick settlement currency
USD, EUR, GBP, or stablecoin. The processor auto-converts on confirmation if fiat is selected.
Test with a live order
Real money, small amount. Verify the order transitions from pending to paid in Shopify admin.
Refund flow rehearsal
Run a refund from Shopify admin. Confirm the processor creates the outbound transaction and the customer receives tokens.
Enable on live storefront
Add the payment method to your themes. Update FAQ and returns policy to include crypto.
WooCommerce Integration
WooCommerce exposes a full payment gateway API, which is why the crypto integration story is cleaner than Shopify. The plug-in registers as a first-class gateway next to PayPal and Stripe.
- Install the plug-in. From WordPress.org or the processor's site. Activate it under WooCommerce, Settings, Payments.
- Paste credentials. API key, webhook secret, settlement wallet or bank details.
- Configure chains and assets. Most shops enable BTC, ETH, and USDC on at least Ethereum and one L2 or Tron.
- Test in sandbox. Most processors offer a test mode with zero-value confirmations. Validate order state transitions.
- Switch to live. Flip the mode, run one small real-money order end to end, then promote to production.
Direct API Integration: The 4 Endpoints That Matter
If you are on a bespoke stack, Medusa, Saleor, a homegrown cart, or a SaaS billing engine, the integration collapses to four endpoints. Everything else is polish.
| Endpoint | Purpose | Key fields |
|---|---|---|
| POST /invoices | Create a new crypto invoice for an order. | order_id, fiat_amount, fiat_currency, callback_url, customer_email |
| GET /invoices/:id | Poll invoice status (for reconciliation or UI fallback). | status (new, pending, paid, expired, invalid) |
| POST /webhooks (inbound) | Receive status changes from the processor in near real time. | event_type, invoice_id, tx_hash, paid_at, final_amount |
| POST /refunds | Send tokens back to the customer. | invoice_id, amount, destination_address, reason |
Webhook discipline
- Always verify the signature. Use the shared secret plus an HMAC check. Reject unsigned or mismatched payloads.
- Treat webhooks as idempotent. Processors retry. Deduplicate by event id.
- Acknowledge fast. Return 2xx within 5 seconds. Do the heavy work async.
- Fall back to polling. Every order should have a "check status" job that runs if no webhook arrives within the expected window.
Refunds, Chargebacks, and Customer Service
Refunds are not chargebacks. On-chain transactions are final, so a refund is a fresh outbound transfer, not a reversal. This changes how your support team handles disputes and returns.
Accounting and Reconciliation
For finance, a crypto transaction needs to look almost identical to a card transaction. Same date, same amount in fiat, a clear reference, and a cost basis that survives an audit.
- Capture the TxID. Store the blockchain transaction hash against your order. It is the single most useful reference for any later dispute.
- Book at fiat equivalent. Use the processor-locked rate at the time of invoice, not the market rate at the moment of writing the ledger.
- Reconcile daily. Processor settlement totals should match your order totals minus fees. Drift signals a bug.
- Export in a tool-friendly format. Xero, NetSuite, and QuickBooks all accept CSV or direct-API imports from mature processors. Do not build this yourself.
- Track cost basis. If you hold stablecoins or native crypto on balance sheet, every transfer is a tax event. Keep lot-level records.
Common Integration Pitfalls
Most first-time integrations stall in the same places. None of these are hard to fix once you know to look for them.
| Pitfall | Fix |
|---|---|
| No webhook signature verification | Always verify with the shared secret before trusting the payload. |
| Webhook handler that returns 5xx under load | Acknowledge fast. Enqueue the real work and process async. |
| Polling only, no webhook | Use both. Webhook is the happy path; polling is the safety net. |
| Mixing refund policies | Pick "same amount of crypto" or "same fiat value" and document it. |
| Launching with too many chains | Start with BTC, ETH, and USDC on one L2. Add chains as demand shows. |
| No reconciliation job | Daily job that compares your orders to processor settlements. Fail loudly on mismatch. |
| Sparse error UX on checkout | Explain what "pending" means. Show the TxID. Tell the customer what to expect. |
Launch Checklist
Run this list the week before you go live. Any "no" means you are not ready yet.
Engineering
- Webhooks verified and idempotent
- Refund flow tested end to end
- Status polling job as a safety net
- TxID stored on every order
Finance
- Settlement bank wired and tested
- Accounting export flow validated
- Daily reconciliation job green
- Cost-basis policy signed off
Customer service
- Macros for "where is my order"
- Refund policy published
- Help article with TxID lookup
- Trained on "no chargeback" reality
Compliance
- KYB complete on processor side
- Sanctions screening confirmed
- Travel Rule path documented
- Returns and refunds pages updated
Integrate With GatewayCrypto
Integration that matches your stack, not the other way around.
GatewayCrypto ships official plug-ins for every major e-commerce platform and a REST API for everything else. You can be live in hours on Shopify or WooCommerce, or run a bespoke integration in a week using our SDKs and sandbox.
- Official plug-ins. Shopify, WooCommerce, Magento, Medusa, Saleor, PrestaShop, OpenCart.
- Complete REST API. Invoices, refunds, webhooks, reconciliation exports, reporting. Signed, versioned, documented.
- Sandbox parity with production. Test real flows with fake money before you commit real dollars.
- SDKs for every stack. Node.js, Python, PHP, Ruby, Go, Java, and a hosted checkout for no-code teams.
- Real engineer support. A dedicated integration engineer on Slack or Teams during your rollout.
Boost Your Business by Accepting Crypto Payments
Get Started
Frequently Asked Questions
Install a plug-in for your platform, wire credentials, run one test order, enable on live. For Shopify and WooCommerce that is usually a one-afternoon job. Direct API integration takes one to three weeks and is only worth it if you have bespoke checkout needs.
No for plug-in-based platforms. Shopify, WooCommerce, and Magento all have click-to-install crypto apps. Yes for direct API work, Medusa, Saleor, or a homegrown cart. Even then, the wire-up is small; most of the effort is treasury and reconciliation.
Yes. Most processors auto-convert the received crypto into the fiat of your choice on confirmation and pay out to your bank on a schedule you pick. Your balance sheet never touches crypto unless you want it to.
Underpayment: the invoice stays pending until the shortfall is made up, or it expires and your checkout releases the order state. Overpayment: most processors credit the customer's remaining balance or auto-refund the delta. Ask your processor which policy they use and document it for your support team.
Call the processor's refund endpoint with the original invoice ID, the amount, and the customer's destination address. The processor creates an outbound on-chain transfer. It is not a chargeback; it is a fresh transaction. Document whether you refund "same token amount" or "same fiat value" and stick to it.
Start with BTC, ETH, USDT on Tron, and USDC on Base or Arbitrum. That covers the bulk of 2026 merchant volume. Add Solana and additional L2s as your buyer data tells you demand is there.
Not for hosted checkout or plug-in flows. The crypto leg has no PCI scope at all. Card-funded fiat-to-crypto flows still carry PCI obligations on the fiat side, but the processor handles them. You remain in scope only for the data you actually collect.
