Installation

Install Solana Pay SDK and get started with payments

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 18 or higher (LTS recommended)
  • Package Manager: pnpm, npm, or yarn
  • TypeScript: Version 4.5+ (recommended but not required)

Install Solana Pay SDK

Choose your preferred package manager:

# Using pnpm (recommended)
pnpm add @solana/pay @solana/web3.js bignumber.js

# Using npm
npm install @solana/pay @solana/web3.js bignumber.js

# Using yarn
yarn add @solana/pay @solana/web3.js bignumber.js

Optional Dependencies

For SPL Token transfers, also install:

# SPL Token support
pnpm add @solana/spl-token

# QR Code generation (for web apps)
pnpm add qrcode
pnpm add -D @types/qrcode  # TypeScript types

TypeScript Configuration

If using TypeScript, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "skipLibCheck": true
  }
}

Framework-Specific Setup

Next.js Configuration

Update next.config.js to transpile Solana Pay packages:

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: [
    '@solana/pay',
    '@solana/web3.js',
    '@solana/spl-token',
  ],
  webpack: (config) => {
    config.resolve.fallback = {
      ...config.resolve.fallback,
      fs: false,
      net: false,
      tls: false,
    };
    return config;
  },
};

export default nextConfig;

Vite Configuration

For Vite-based applications (Vue, React, etc.), update vite.config.js:

import { defineConfig } from 'vite';

export default defineConfig({
  define: {
    global: 'globalThis',
  },
  resolve: {
    alias: {
      stream: 'stream-browserify',
      crypto: 'crypto-browserify',
    },
  },
  optimizeDeps: {
    include: ['@solana/pay', '@solana/web3.js', 'bignumber.js'],
  },
});

React Native Setup

For React Native applications:

# Install React Native specific dependencies
pnpm add react-native-get-random-values
pnpm add @react-native-async-storage/async-storage

# For QR code scanning
pnpm add react-native-qrcode-scanner
pnpm add react-native-permissions

Add to your app's entry point:

// App.js or index.js (top of file)
import 'react-native-get-random-values';

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.js
import { createTransferRequestURL } from '@solana/pay';
import { PublicKey } from '@solana/web3.js';
import BigNumber from 'bignumber.js';

// Test creating a payment URL
const recipient = new PublicKey('recipient-public-key-here');
const amount = new BigNumber(0.01);
const reference = new PublicKey('reference-public-key-here');
const label = 'Test Store';
const message = 'Test payment';

const url = createTransferRequestURL({
  recipient,
  amount,
  reference,
  label,
  message,
});

console.log('Solana Pay URL:', url.toString());

Run the test:

node test-installation.js

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

Buffer/Crypto Polyfills

For browser environments, you may need polyfills:

pnpm add -D @esbuild-plugins/node-globals-polyfill
pnpm add -D @esbuild-plugins/node-modules-polyfill

TypeScript Errors

If you encounter TypeScript errors:

  1. Update to the latest TypeScript version
  2. Add Solana types to your tsconfig.json: 
    {
  "compilerOptions": {
    "types": ["node"]
  }
}

Next Steps

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

Development Tools

Consider installing these helpful development tools:

# Solana CLI (for testing and key generation)
sh -c "$(curl -sSfL https://release.solana.com/v1.14.18/install)"

# Local validator for testing
solana-test-validator

# Wallet adapters for testing
pnpm add @solana/wallet-adapter-react
pnpm add @solana/wallet-adapter-wallets

Resources