How to Add a Crypto Checkout to Shopify Without a Plugin

Shopify's payment plugin ecosystem is huge, but you don't actually need one to accept crypto. A hosted checkout URL and one webhook handler are enough. Here's the pattern we recommend to merchants who want to add a "Pay with crypto" option without introducing a middleman.

Why not a plugin

Shopify apps are convenient but they lock you into whatever the plugin author decided. You inherit their fee structure, their custody model (are they holding funds first?), and their maintenance cadence. If the app is unmaintained, your checkout breaks. If Shopify changes an internal API the app depends on, your integration breaks. For crypto — where the moving parts are custody and settlement — trusting a third party in the middle is exactly the wrong direction.

The alternative is straightforward: use Shopify's built-in theme customization to add a payment button that opens a hosted checkout URL outside the standard Shopify flow.

The one-URL approach

Solpaygate generates a checkout URL from a single API call. The customer clicks a button on your cart page, a payment session is created against their cart ID, and they're redirected to app.solpaygate.com/pay?token=... to complete payment. When it clears, they come back to your Shopify order-status page.

You need three pieces:

• A Liquid edit or Shopify theme extension that adds a "Pay with Crypto" button to the cart page.
• A small serverless endpoint (Cloudflare Workers, Vercel, whatever) that calls Solpaygate's session-create endpoint and returns the URL to the browser.
• A webhook handler that updates the Shopify order when Solpaygate confirms payment.

Setting up the button

Drop a "Pay with Crypto" button on the cart page. When clicked, it calls your serverless endpoint with the cart total and cart token. That endpoint makes one call to Solpaygate:

POST /api/company/{companyId}/payment-session
X-Api-Key: sk_live_...

{
  "userId": "shopify_customer_1234",
  "orderId": "cart_9876abcd",
  "description": "Order #1234 — 3 items",
  "returnUrl": "https://shop.example.com/orders/1234/complete"
}

You get back { token, url, expiresAt }. Redirect the customer to the url; they pay from any Solana wallet; and when the payment confirms, the returnUrl brings them back to Shopify's thank-you page. The whole handoff is a single redirect in each direction.

Handling order marks

Shopify won't know about the payment unless you tell it. In your webhook handler — the one Solpaygate calls when the transfer confirms — call the Shopify Admin API to mark the order paid:

1. Match the incoming payment by orderId (the cart_9876abcd you passed in).
2. Use Shopify's transactions endpoint to record the payment against the draft or order.
3. Update the order's financial_status to paid.
4. Optionally, tag the order with the paymentId so support can trace it later.

Keep the handler idempotent — Solpaygate retries webhooks, and marking an already-paid order paid a second time shouldn't create a duplicate transaction row.

Reconciling with Shopify orders

Two systems, one truth: your Solpaygate dashboard shows every payment, Shopify shows every order. A nightly reconciliation script keeps them aligned:

• Pull the last 24 hours of confirmed Solpaygate payments.
• Fetch the matching Shopify order by the orderId you set.
• Flag any Solpaygate payment without a matching paid order — usually the customer paid after the session expired and needs a manual mark.
• Flag any Shopify order marked paid without a Solpaygate confirmation — this shouldn't happen if your webhook is idempotent, but it's cheap to check.

If you're also selling recurring products, the same pattern extends cleanly to renewals — see our write-up on accepting crypto payments for SaaS subscriptions. And if you're still deciding between session-based and shareable-link checkout, our sessions vs links comparison covers the tradeoffs before you commit to a pattern.