---
title: Solana Pay
description: Generate payment URLs, QR codes, and transactions
draft: true
---

<Callout type="caution">
  The Commerce Kit is currently in beta. APIs may change before the stable
  release. For additional details, see the [Commerce Kit
  documentation](/docs/tools/commerce-kit).
</Callout>

[Solana Pay](https://solanapay.com) is a standard protocol for encoding payment
requests as URLs. These URLs can be shared as links, encoded as QR codes for
mobile wallets, or used to build payment transactions programmatically.

The `@solana-commerce/solana-pay` package provides URL encoding/parsing, QR code
generation, and transaction building—compatible with
[@solana/kit](https://github.com/anza-xyz/kit).

## Installation

```bash
pnpm add @solana-commerce/solana-pay
```

## Creating Payment URLs

Use `encodeURL` to create a `solana:` protocol URL that wallets can parse:

```typescript
import { encodeURL } from "@solana-commerce/solana-pay";

const url = encodeURL({
  recipient: address("merchant-wallet-address"),
  amount: 100000000n, // 0.1 SOL in lamports
  label: "Coffee Shop",
  message: "Thanks for your order!"
});

console.log(url.toString());
// solana:merchant...?amount=0.1&label=Coffee%20Shop&message=...
```

### URL Parameters

| Parameter   | Type        | Description                               |
| ----------- | ----------- | ----------------------------------------- |
| `recipient` | `Address`   | Merchant wallet address (required)        |
| `amount`    | `bigint`    | Amount in lamports or token minor units   |
| `splToken`  | `Address`   | SPL token mint address (omit for SOL)     |
| `reference` | `Address[]` | Unique reference(s) for tracking payments |
| `label`     | `string`    | Merchant name shown in wallet             |
| `message`   | `string`    | Message shown before payment              |
| `memo`      | `string`    | Onchain memo attached to transaction      |

### SPL Token Payments

For stablecoin payments, specify the token mint:

```typescript
import { encodeURL } from "@solana-commerce/solana-pay";

const url = encodeURL({
  recipient: address("merchant-wallet"),
  amount: 25000000n, // 25 USDC (6 decimals)
  splToken: USDC_MINT,
  label: "My Store"
});
```

### Payment Tracking with References

Generate a unique reference to identify specific payments:

```typescript
import { encodeURL } from "@solana-commerce/solana-pay";
import { address, generateKeyPairSigner } from "@solana/kit";

const orderReference = (await generateKeyPairSigner()).address;

const url = encodeURL({
  recipient: address(MERCHANT_WALLET_ADDRESS),
  amount: 500000000n, // 0.5 SOL
  reference: orderReference,
  memo: `Order-${Date.now()}`
});

// Query the blockchain later for transactions containing this reference
```

## Generating QR Codes

Use `createQR` to generate scannable QR codes for mobile wallets:

```typescript
import { createQR, encodeURL } from "@solana-commerce/solana-pay";
import { address } from "@solana/kit";

const url = encodeURL({
  recipient: address(MERCHANT_WALLET_ADDRESS),
  amount: 100000000n,
  label: "Coffee Shop"
});

const qrCode = await createQR(
  url.toString(),
  400, // size in pixels
  "white", // background
  "black" // foreground
);

// Use as image source
document.getElementById("qr").src = qrCode;
```

### Styled QR Codes

For branded QR codes with logos and custom styling:

```typescript
import { createStyledQRCode, encodeURL } from "@solana-commerce/solana-pay";

const qr = await createStyledQRCode(url.toString(), {
  width: 600,
  margin: 3,
  color: {
    dark: "#9945FF", // Solana purple
    light: "#FFFFFF"
  },
  errorCorrectionLevel: "H",
  dotStyle: "dots",
  cornerStyle: "extra-rounded",
  logo: "/your-logo.png",
  logoSize: 120
});
```

## Building Transactions

Use `createTransfer` to build a complete transaction for signing:

```typescript
import { createTransfer } from "@solana-commerce/solana-pay";

const transaction = await createTransfer(
  client.rpc,
  address(SENDER_WALLET_ADDRESS),
  {
    recipient: address(MERCHANT_WALLET_ADDRESS),
    amount: 100000000n, // 0.1 SOL
    memo: "Coffee purchase"
  }
);
```

For SPL tokens, include the mint address:

```typescript
const USDC_MINT = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

const transaction = await createTransfer(
  client.rpc,
  address(SENDER_WALLET_ADDRESS),
  {
    recipient: address(MERCHANT_WALLET_ADDRESS),
    amount: 25000000n, // 25 USDC
    splToken: USDC_MINT,
    reference: [orderReference],
    memo: "Order #12345"
  }
);
```

## Parsing URLs

Validate and extract data from Solana Pay URLs:

```typescript
import { parseURL, ParseURLError } from "@solana-commerce/solana-pay";

try {
  const parsed = parseURL("solana:merchant...?amount=1.5&label=Store");

  console.log(parsed.recipient); // Address
  console.log(parsed.amount); // 1500000000n (lamports)
  console.log(parsed.label); // "Store"
} catch (error) {
  if (error instanceof ParseURLError) {
    console.error("Invalid URL:", error.message);
  }
}
```