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.0

Basic 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. 49454e4f4d5f434e4f5904434556494d4345191c1a56181a181c1a1d