Solana Pay Basics
7 examples for payment requests and QR flows - 4 basic and 3 intermediate.
Prerequisites
npm install @solana/pay @solana/kit@7.0.0Basic Examples
1. Transfer Request URL
Solana Pay URLs encode recipient, amount, and label.
import { encodeURL } from "@solana/pay";
import { address } from "@solana/kit";
const url = encodeURL({
recipient: address("MERCHANT_PUBKEY"),
amount: 1_000_000n,
label: "Coffee",
});- Wallets parse URLs to prefill transfers.
- Amounts in lamports as bigint.
- HTTPS or solana: scheme depending on context.
2. QR Code for POS
Render URL as QR for in-person checkout.
import QRCode from "react-qr-code";
// <QRCode value={url.toString()} />- Test scan distance and lighting for events.
- Include human-readable label under QR.
- Expire or rotate URLs for one-time invoices when needed.
3. Reference Pubkey Tracking
Attach reference account to correlate payments.
// encodeURL({ ..., reference: [referencePubkey] })- Monitor reference via RPC or websocket.
- Unique reference per checkout session.
- See Transaction Requests.
4. Merchant Display Metadata
Label and message fields improve wallet UX.
encodeURL({ label: "Shop", message: "Order #1234", ... });- Keep message short - wallet UI truncates.
- Localize label for international customers.
Intermediate Examples
5. Transaction Request Flow
Server returns partially built transaction instead of simple transfer.
// GET https://merchant.com/api/solana-pay?account=...- Enables swap or mint in one wallet approval.
- Requires HTTPS endpoint you control.
- Spec overlaps with Solana Actions.
6. Verify Payment Settled
import { createSolanaRpc } from "@solana/kit";
const rpc = createSolanaRpc(process.env.RPC_URL!);
// find tx mentioning reference + amount- Do not mark order paid on client-side guess.
- Wait for confirmed commitment minimum.
- Handle partial payments explicitly.
7. Link to Actions / Blinks
Shareable action URLs embed in social posts.
https://actions.example.com/swap?...
- Blinks unfurl in supported apps.
- See Blinks and Actions (the spec).
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.