Installation

Get started with Solana Pay by installing the JavaScript SDK and setting up your development environment. The SDK is framework-agnostic and works with any JavaScript environment.

System Requirements

• Node.js: Version 20 or higher (required for Ed25519 crypto.subtle support)
• Package Manager: pnpm, npm, or yarn
• TypeScript: Version 5+ (recommended but not required)

Install Solana Pay SDK

Choose your preferred package manager:

# Using pnpm (recommended)
pnpm add @solana/pay@beta @solana/kit

# Using npm
npm install @solana/pay@beta @solana/kit

# Using yarn
yarn add @solana/pay@beta @solana/kit

Peer Dependencies

The following are peer dependencies of @solana/pay and must be installed alongside it:

Optional Dependencies

For transfer creation and validation (SOL and SPL token transfers), also install:

pnpm add @solana-program/system @solana-program/token @solana-program/token-2022 @solana-program/memo

For the client factories (createMerchantClient, createWalletClient), also install the kit plugins:

pnpm add @solana/kit-plugin-rpc @solana/kit-plugin-payer @solana/kit-plugin-instruction-plan

TypeScript Configuration

If using TypeScript, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Environment Setup

Development Environment

Set up environment variables for development:

# .env.local
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_NETWORK=devnet

Production Environment

For production, use mainnet endpoints:

# .env.production
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_NETWORK=mainnet-beta

Verify Installation

Create a simple test to verify everything is working:

// test-installation.ts
import { address } from "@solana/kit";
import { encodeURL } from "@solana/pay";

// Test creating a payment URL
const recipient = address("FvJ8k8HhXp4a3zQyFMZd4FvEqcYdYE7gSZWxrEBRfBsB");

const url = encodeURL({
  recipient,
  amount: 0.01,
  label: "Test Store",
  message: "Test payment"
});

console.log("Solana Pay URL:", url.toString());
// Output: solana:FvJ8k8Hh...?amount=0.01&label=Test%20Store&message=Test%20payment

Run the test:

npx tsx test-installation.ts

You should see a valid Solana Pay URL in the console.

Common Issues and Solutions

Module Resolution Errors

If you see errors like "Cannot resolve module '@solana/pay'":

1. Clear your package manager cache:

   # pnpm
   pnpm store prune
   
   # npm
   npm cache clean --force
   
   # yarn
   yarn cache clean

2. Delete node_modules and reinstall:

   rm -rf node_modules
   pnpm install

TypeScript Errors

If you encounter TypeScript errors:

1. Update to the latest TypeScript version (5+)
2. Ensure moduleResolution is set to "bundler" or "nodenext" in your tsconfig.json

Next Steps

Now that you have Solana Pay installed, choose your integration path:

• Transfer Requests - Simple payment URLs for basic transfers
• Transaction Requests - Interactive payment flows
• QR Code Integration - Generate QR codes for mobile payments

Development Tools

Consider installing these helpful development tools:

# Solana CLI (for testing and key generation)
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

# Local validator for testing
solana-test-validator

Resources

• GitHub Repository - Source code and examples
• Solana Cookbook - Solana development recipes