Overview

Understanding the Solana Pay protocol and implementation

Solana Pay is a standard protocol and set of reference implementations that enable developers to incorporate decentralized payments into their apps and services. It provides a unified approach to payments across the Solana ecosystem, ensuring compatibility between wallets, apps, and services.

Protocol Overview

Solana Pay defines two main types of payment requests:

Transfer Requests (Non-Interactive)

Transfer requests describe simple SOL or SPL token transfers using URL parameters. The wallet can directly compose and sign the transaction without additional server communication.

solana:recipient?amount=1.5&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Use Cases:

  • Simple payments and donations
  • QR code payments at point of sale
  • Payment links in emails or messages
  • Mobile app deep linking

Transaction Requests (Interactive)

Transaction requests enable complex interactions by having the wallet communicate with a server to compose any Solana transaction. This unlocks advanced use cases beyond simple transfers.

solana:https://merchant.com/api/payment

Use Cases:

  • NFT minting at point of sale
  • Dynamic pricing and discounts
  • Multi-step DeFi transactions
  • Loyalty program integration
  • Custom business logic

Key Benefits

For Developers

  • Standard Protocol: One implementation works across all Solana wallets
  • Framework Agnostic: Use with any web framework or mobile platform
  • Type Safety: Complete TypeScript support in the JavaScript SDK
  • Flexible: Simple transfers to complex multi-instruction transactions

For Users

  • Fast: Transactions confirm in under a second
  • Cheap: Average cost of $0.0005 per transaction
  • Secure: No intermediaries or third-party processors
  • Universal: Works with any Solana wallet

For Merchants

  • No Fees: Direct payments without processing fees
  • Real-time: Instant settlement and confirmation
  • Global: Accept payments from anywhere in the world
  • Composable: Integrate with DeFi protocols and NFT marketplaces

Technical Architecture

URL Scheme

Solana Pay uses a custom URL scheme solana: that works across web browsers and mobile operating systems:

  • Web: URLs can be used as links or encoded in QR codes
  • Mobile: Deep linking integration with wallet apps
  • Desktop: Protocol handlers for seamless wallet launching

JavaScript SDK

The @solana/pay SDK provides utilities for:

  • Creating payment request URLs
  • Validating payment transactions
  • Finding transactions by reference
  • QR code generation and styling

Wallet Integration

Supporting wallets implement:

  • URL scheme handling and parsing
  • Transaction composition and validation
  • User confirmation flows
  • Transaction broadcasting and monitoring

Payment Flow Examples

Web App to Mobile Wallet

  1. Web app generates QR code with Solana Pay URL
  2. User scans QR code with wallet app
  3. Wallet parses URL and shows payment details
  4. User confirms payment in wallet
  5. Wallet signs and broadcasts transaction
  6. Web app detects payment confirmation

Web App to Browser Wallet

  1. Web app shows "Pay with Solana" button
  2. User clicks button to launch wallet
  3. Wallet extension shows payment confirmation
  4. User approves transaction
  5. Transaction is signed and sent
  6. Web app receives payment confirmation

Mobile App to Mobile Wallet

  1. Mobile app creates payment deep link
  2. Deep link launches wallet app
  3. Wallet shows payment confirmation
  4. User approves or rejects payment
  5. Wallet returns to original app
  6. App receives payment result

Security Considerations

For Merchants

  • Validate Transactions: Always verify transaction details on-chain
  • Use References: Include unique reference keys to identify payments
  • Server-side Validation: Calculate amounts and validate payments server-side
  • Rate Limiting: Implement appropriate rate limits on payment endpoints

For Wallet Developers

  • URL Validation: Validate and sanitize all URL components
  • User Confirmation: Always show clear payment details to users
  • Transaction Validation: Verify transaction contents before signing
  • HTTPS Only: Only allow HTTPS URLs for transaction requests

Integration Patterns

E-commerce Checkout

  1. Customer adds items to cart
  2. Merchant generates payment request with order details
  3. Customer scans QR code or clicks payment button
  4. Wallet shows itemized receipt and total
  5. Customer confirms payment
  6. Merchant validates transaction and fulfills order

Point of Sale

  1. Cashier enters sale amount
  2. POS system displays QR code
  3. Customer scans with mobile wallet
  4. Payment processes instantly
  5. Receipt printed automatically

Subscription Services

  1. User subscribes to service
  2. Service creates recurring payment schedule
  3. Automated system generates payment requests
  4. User approves payments through wallet
  5. Service tracks payment status

Best Practices

URL Generation

  • Use HTTPS for all transaction request endpoints
  • Include descriptive labels and messages
  • Generate unique references for payment tracking
  • Validate all parameters before URL creation

Transaction Handling

  • Always validate transactions server-side
  • Use appropriate confirmation counts for security
  • Implement proper error handling and retries
  • Log payment events for reconciliation

User Experience

  • Provide clear payment confirmations
  • Show transaction status updates
  • Handle wallet connection gracefully
  • Support multiple wallet options

Next Steps

Ready to integrate Solana Pay? Start with these guides:

Resources