� Solana Pay Checkout Widget

A seamless Web3 payment solution that bridges traditional payments with Solana blockchain

� Live Demo

---

✨ Features

🌟 For Merchants ⚡ Quick Setup - Get started in under 5 minutes 🎯 Flexible Integration - React/Typescript component 💰 Payment Support - Solana Pay - SOL, USDC, USDT 🔐 Secure - Non-custodial, secure by design

🎁 For Customers 📱 Mobile-First - QR code payments for mobile wallets ⚡ Instant Settlements - Sub-second transaction confirmations 🔗 Multiple Wallets - Phantom, Backpack, Solflare support 💳 Fallback - Wallet & QR code payments

---

🚀 Quick Start

1️⃣ Installation

npm install solana-pay-widget
# or
yarn add solana-pay-widget

2️⃣ Basic Usage

import { CheckoutWidget, WalletConnectionProvider } from 'solana-pay-widget';
import 'solana-pay-widget/dist/index.css';

function App() {

  return (
    <WalletConnectionProvider rpcEndpoint='https://api.devnet.solana.com'> 
        <CheckoutWidget
          checkoutId="demo_checkout_123"
          merchantWallet="4rbzcZsLxEefKdyho3U2dc5tfKUMdSM4vyRQhAkL4EHX"
          amount={0.001}
          currency="SOL"
          productName="Premium Subscription"
          description="Monthly premium subscription with all features"
          isOpen={true}
          onClose={() => {}}
          onSuccess={(txnId) => {}}
          onError={(err) => {}}
        />
      </WalletConnectionProvider>
  );
}

3️⃣ Advanced Configuration

<CheckoutWidget
  checkoutId="demo_checkout_123"
  merchantWallet="4rbzcZsLxEefKdyho3U2dc5tfKUMdSM4vyRQhAkL4EHX"
  amount={0.001}
  currency="SOL"
  productName="Premium Subscription"
  description="Monthly premium subscription with all features"
  isOpen={true}
  onClose={() => {}}
  onSuccess={(txnId) => {}}
  onError={(err) => {}}
/>

---

🏗️ Architecture Overview

graph TB
    A[👤 User] -->|Creates Payment| B[🛒 Checkout]
    B --> C[💳 Payment Method]
    C -->|Solana Pay| D[🔗 Solana Blockchain]
    D -->|Verify| F[⚡ Backend API]
    F -->|Update Status| G[✅ Order Complete]
    F -->|Success Return| H[📧 You can store TxnId in DB]

Loading

---

Core Components

<CheckoutWidget />

Prop	Type	Required	Description
checkoutId	string	✅	Unique checkout identifier for tracking
merchantWallet	string	✅	Merchant's Solana wallet address (recipient)
amount	number	✅	Payment amount (e.g., 0.001 for SOL)
currency	'SOL' | 'USDC' | 'USDT'	✅	Payment currency
productName	string	✅	Product/service name shown in widget
description	string	❌	Product description
theme	'light' | 'dark' | 'auto'	❌	Widget theme (default: 'light')
enableNftReceipt	boolean	❌	Enable NFT receipt minting (not implemented)
webhookUrl	string	❌	Payment webhook URL (not implemented)
onSuccess	(txId: string) => void	❌	Success callback with transaction ID
onError	(error: Error) => void	❌	Error callback
onClose	() => void	❌	Close callback
className	string	❌	Custom CSS class for styling
isOpen	boolean	✅	Control widget modal visibility

<WalletConnectionProvider />

Prop	Type	Required	Description
rpcEndpoint	string	❌	Solana RPC endpoint (default: devnet)
children	ReactNode	✅	Child components

Supported Wallets:

• 🦊 Phantom
• ☀️ Solflare
• 🅰️ Alpha Wallet

---

🌐 Network Configuration

Devnet (Testing)

<WalletConnectionProvider rpcEndpoint='https://api.devnet.solana.com'>
  <CheckoutWidget
    merchantWallet="4rbzcZsLxEefKdyho3U2dc5tfKUMdSM4vyRQhAkL4EHX"
    // ... other props
  />
</WalletConnectionProvider>

Mainnet (Production)

<WalletConnectionProvider rpcEndpoint='https://api.mainnet-beta.solana.com'>
  <CheckoutWidget
    merchantWallet="YOUR_MAINNET_WALLET_ADDRESS"
    // ... other props
  />
</WalletConnectionProvider>

⚠️ Important Notes:

• Widget automatically uses appropriate token addresses based on network
• USDC/USDT payments require token accounts (automatically created if needed)
• Always test on devnet before deploying to mainnet

---

💳 Payment Methods

SOL Payments

• Direct wallet-to-wallet transfers
• Minimum amount: 0.000001 SOL
• Includes transaction fee estimation

Token Payments (USDC/USDT)

• Requires associated token accounts
• Automatic token account creation for recipients
• 6 decimal precision for both USDC and USDT

QR Code Payments

• Mobile wallet compatible
• Real-time transaction polling
• Automatic payment verification

---

🔧 Error Handling

The widget includes comprehensive error handling:

const handleError = (error) => {
  switch(error.message) {
    case 'Insufficient SOL balance':
      // Handle insufficient funds
      break;
    case 'Transaction was cancelled':
      // Handle user cancellation
      break;
    case 'Network error':
      // Handle connection issues
      break;
    default:
      // Handle other errors
  }
};

Common Error Types:

• Insufficient funds - User needs more SOL/tokens
• Token account not found - User needs to create token account
• Transaction was cancelled - User rejected transaction
• Network error - Connection or RPC issues

---

📱 QR Code Payment Flow

1. QR Generation - Secure Solana Pay URL created
2. Mobile Scan - User scans with mobile wallet
3. Transaction - Payment processed on blockchain
4. Verification - Auto-polling confirms payment
5. Completion - Success callback triggered

QR Code Features:

• Auto-generated reference for tracking
• Error correction for reliable scanning
• Timeout after 5 minutes
• Real-time status updates

---

🎨 Custom Styling

<CheckoutWidget
  className="my-custom-checkout"
  theme="dark"
  // ... other props
/>

.my-custom-checkout {
  border-radius: 20px;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
}

.my-custom-checkout .sp-checkout-header {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

Available CSS Classes:

• .sp-modal-overlay - Modal backdrop
• .sp-modal-container - Main modal container
• .sp-checkout-header - Header section
• .sp-qr-payment - QR code container
• .sp-wallet-payment - Wallet payment section