Implementing a Blockchain Payment Link in Your Checkout

A blockchain payment link lets a customer pay a fixed amount by clicking a URL that encodes the invoice details and routes the transaction through a crypto network. It reduces checkout friction for users with wallets, while giving merchants verifiable, near-instant settlement. Done right, it’s as simple as adding a button—yet the design details matter.

What a blockchain payment link actually does

At its core, a payment link is a URI that pre-fills recipient address, amount, and sometimes memo fields in a wallet. The user clicks, their wallet opens, and the transaction is staged for approval. Networks use different URI schemes: Bitcoin uses bitcoin:, Ethereum uses ethereum: or EIP-681, Solana uses solana:, and Lightning uses lightning: (BOLT11). The mechanism is standard enough to integrate cleanly with web and mobile checkouts.

Example: an EIP-681 link might look like ethereum:0xReceiver?value=1000000000000000000 for 1 ETH in wei. A Lightning invoice is a single encoded string that also carries expiry and routing hints.

When a payment link fits your checkout

Payment links shine for digital goods, cross-border orders, and buyers already using self-custody wallets. They’re less ideal where chargebacks are required by policy, or when price quotes must hold for long windows without volatility protection. If you add fiat as the default and crypto as an option, you’ll catch the upside without bloating support.

Core design decisions

Before writing code, settle four decisions: network support, pricing model, settlement strategy, and confirmation rules. These shape every downstream choice from URI format to webhook payloads.

1. Choose networks: Start with one UTXO chain (Bitcoin or Lightning) and one account-based chain (Ethereum or a popular L2). Covering both patterns improves compatibility with common wallets.
2. Set pricing logic: Price in your store currency and convert to crypto amount at quote time. Freeze the quote for a short window to avoid slippage; 10–15 minutes works for most carts.
3. Settlement path: Decide if you’ll auto-convert to fiat via a processor, keep crypto on balance, or split by threshold. Each path has different treasury and tax consequences.
4. Confirmation policy: Define “paid” precisely. For Bitcoin, you might mark as paid on zero-conf for Lightning, one confirmation for on-chain small orders, and three for high-value items. For EVM chains, consider block confirmations and potential chain reorg depth.

Document these choices in your merchant playbook. It keeps support aligned when customers ask why a payment still shows “pending.”

Implementation patterns that work

You can build payment links in-house or via a payment service provider (PSP). The choice hinges on your appetite for wallet, pricing, and reconciliation logic.

• PSP-managed links: The PSP generates short-lived links, handles rate locking, addresses, confirmations, and webhooks. You store a single invoice ID and react to events.
• Hybrid: You generate EIP-681 or BOLT11 invoices but delegate rate conversion and fraud checks to an API. This keeps control over UX while outsourcing the hard edges.
• Self-managed: You run nodes or use provider endpoints, derive addresses per order, and post your own webhooks after parsing mempool/blocks. Highest control, highest ops load.

For most teams, PSP-managed links get you live in a sprint, with room to iterate toward hybrid later.

Generating the link: examples by network

The goal is the same across chains: encode receiver, amount, and metadata, then show both a button and a QR. Here’s how it differs per network.

Ethereum and EVM chains (EIP-681)

EIP-681 supports native token value and token transfers. For native ETH on mainnet:

ethereum:0xReceiverAddress?value=1000000000000000000

For ERC-20 USDC (value in smallest unit):

ethereum:0xUSDCContract/transfer?address=0xReceiverAddress&uint256=1000000

Add chain_id when you target L2s to avoid mis-sends. Many wallets also respect gas and gasPrice, but keep those optional to prevent brittle links.

Bitcoin on-chain (BIP-21)

A BIP-21 URI embeds amount, label, and message:

bitcoin:bc1qreceiver...?...amount=0.0025&label=Order%201234&message=Invoice%201234

Use bech32 or bech32m addresses and one link per invoice. Rotate addresses to simplify reconciliation and privacy.

Lightning (BOLT11)

Lightning invoices are preimages encoded as a single string, often exposed via lightning: URI. Include expiry, amount, and description. Example flow: request invoice from your node or PSP, show QR + copy, monitor payment via an event stream.

Solana pay links

Solana’s solana: scheme supports amount, reference, and SPL tokens. If you use USDC on Solana, lock the mint address in the link to avoid chain mix-ups.

Always include an internal invoice ID in a memo/reference tag when the standard allows it. It saves hours during support escalations.

Checkout UX that reduces drop-off

Crypto-savvy users expect speed and clarity. The way you present the link has an outsized impact on completion rates.

1. Offer both “Open in wallet” and QR: Desktop users scan QR with mobile wallets; mobile users tap the deep link. Detect platform and nudge accordingly.
2. Show a countdown timer: If you lock rates for 15 minutes, display the exact time left. When it expires, regenerate the link automatically.
3. Display network fees and final totals: A tiny note like “Network fee paid by customer; we don’t add a surcharge” prevents confusion at approval time.
4. Handle partial/overpayments: If the user sends 0.98 instead of 1.00 due to fees or slippage, present a one-click “Send difference” link with the remaining amount.

A micro-example: a customer on mobile taps “Pay with ETH,” their wallet opens with the EIP-681 link, they approve, your UI detects the pending tx hash, and the page updates to “Confirming (1/2).” The order auto-advances when confirmations hit the threshold.

Pricing, volatility, and refunds

Volatility is manageable if you limit the exposure window. Quote in your base currency and convert at payment start; refresh at expiry. For refunds, avoid sending back the original crypto amount. Instead, fix a refund policy: refund the fiat-equivalent at the time of refund (minus network fees) or return the exact crypto received. Communicate this clearly at checkout.

For compliance, log the FX rate used, fee breakdown, and wallet addresses. Store the on-chain transaction hash alongside your order ID.

Security and confirmation model

Security comes down to address control, tamper resistance, and confirmation thresholds. Use HTTPS everywhere, sign server responses, and never expose private keys in the browser. If you host your own nodes, pin versions and monitor peers. If you use third-party endpoints, add redundancy to avoid false negatives on payment detection.

Confirmations should reflect risk. Low-value digital downloads can settle on Lightning instantly. Mid-value goods on Ethereum might wait 1–2 blocks. High-value on Bitcoin might wait 3–6 confirmations, with a clear progress state in the UI.

Minimal architecture for going live

You don’t need a mountain of infrastructure to start. A lean design gets you to production while keeping future options open.

This setup lets you switch providers without rewriting your checkout. Keep your interfaces narrow: one function to request a link, one to verify a payment, one to settle a refund.

Step-by-step: adding a payment link to checkout

Here’s a practical path you can adapt to most stacks, from SPA front ends to server-rendered sites.

1. Create an order record with amount in base currency and a status of “awaiting crypto.”
2. Request a crypto quote and payment link from your PSP or generator with a 15-minute TTL.
3. Render a modal with the link button, QR code, network name, fees note, and countdown timer.
4. Subscribe to payment events via webhook or poll an order status endpoint. Update UI on “received,” “confirming,” and “confirmed.”
5. On expiry without payment, offer “Refresh quote” to generate a new link. Invalidate old links server-side.
6. When confirmed, finalize the order, send the receipt, and store transaction metadata and FX rate.

This flow avoids race conditions, handles expired links gracefully, and gives users constant feedback.

Testing and edge cases worth simulating

Don’t ship blind. Spin up testnet or sandbox modes and run a checklist across devices and wallets.

• Cancelled approval in wallet: ensure the checkout returns to a ready state.
• Partial payment: present a “pay remainder” link and merge the receipts.
• Overpayment: accept and mark the surplus for refund or store credit.
• Expired quote paid late: flag for manual review; show a “processing” banner to the user.
• Wrong network: detect and warn if the transaction appears on an unexpected chain.

A tiny scenario: a user pays an ERC-20 on the wrong chain (e.g., USDC on a sidechain). If your link encoded chain ID and token mint, your system rejects mismatched receipts immediately and prompts a new, correct link.

Where this goes next

Payment links are evolving toward account abstraction, session keys, and gas sponsorship, which will hide much of the signing complexity. For now, the combination of clear URIs, strict quote windows, and clean webhooks delivers a fast, auditable path from cart to confirmation.