Skip to main content

​
WhiskyPay Development Guide

This guide provides comprehensive information for developers working on the WhiskyPay platform. It covers environment setup, development workflows, and system architecture.

​
System Architecture

WhiskyPay consists of three main components that work together: 
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    React App    │     │  Payment Gateway │     │     Workers     │
│                 │────▶│  (Next.js API)   │────▶│   (BullMQ)      │
│  SDK            │     │                 │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Solana Wallet  │     │    Supabase     │     │      Redis      │
│                 │     │    Database     │     │     Queue       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
  1. SDK: React components and utility functions for merchants to integrate
  2. Payment Gateway: Backend API and database for processing payments
  3. Workers: Background processing for webhooks and emails

​
Development Environment Setup

​
Prerequisites

  • Node.js v16+
  • npm or yarn
  • Git
  • Redis (for local development)
  • Supabase account (or local Supabase setup)
  • Solana CLI tools (optional but recommended)

​
Clone Repositories

# Clone all three repositories
https://github.com/weknowyourgame/WhiskyPay sdk workers & payment-gateway

​
SDK Setup

cd sdk
npm install
npm run build
To develop the SDK with local linking: 
# In the SDK directory
npm link

# In your test application
npm link @whisky-peak/whisky-pay-sdk

​
Payment Gateway Setup

cd payment-gateway
npm install

# Create .env file with Supabase credentials
cp .env.example .env
# Edit .env with your actual credentials

# Start development server
npm run dev

​
Workers Setup

cd workers
npm install

# Create .env file with Redis credentials
cp .env.example .env
# Edit .env with your actual credentials

# Start workers in development mode
npm run dev

​
Local Development Workflow

For a complete local development environment, run all three components:
  1. Start the Payment Gateway: cd payment-gateway && npm run dev
  2. Start the Workers: cd workers && npm run dev
  3. Start your test application that uses the SDK

​
Testing the End-to-End Flow

  1. Create a test merchant in your local database
  2. Use the SDK in a test app to create a payment session
  3. Complete a payment using a Solana wallet (Phantom in dev mode)
  4. Verify webhook callbacks and email notifications

​
Project Structure

​
SDK Structure

sdk/
├── src/
│   ├── index.ts             # Main exports
│   ├── PaymentModal.tsx     # Payment UI component
│   ├── createSession.ts     # Create payment session
│   ├── fetchSession.ts      # Fetch session details
│   ├── verifyPayment.tsx    # Verify payment transactions
│   └── Tokens.ts            # Token definitions
├── dist/                    # Compiled code
├── package.json
└── tsconfig.json

​
Payment Gateway Structure

payment-gateway/
├── app/                     # Next.js app directory
│   ├── api/                 # API routes
│   │   ├── session/         # Session API
│   │   ├── verify/          # Verification API
│   │   └── webhook/         # Webhook API
│   ├── components/          # React components
│   ├── lib/                 # Utility functions
│   ├── models/              # Database models
│   └── page.tsx             # Main landing page
├── .env                     # Environment variables
├── middleware.ts            # Next.js middleware
└── package.json

​
Workers Structure

workers/
├── index.ts                 # Main worker file
├── .env                     # Environment variables
└── package.json

​
Data Flow

​
Payment Process Flow

  1. Session Creation:
    • Merchant creates a session via SDK
    • Gateway generates a session ID and stores details in Supabase
    • Session details returned to frontend
  2. Payment Execution:
    • Customer connects their wallet via the PaymentModal component
    • SDK fetches session details from the Gateway
    • Customer selects token and makes payment
    • Transaction is submitted to Solana blockchain
  3. Payment Verification:
    • SDK sends transaction signature to Gateway for verification
    • Gateway verifies the transaction on Solana
    • On success, Gateway updates the database and queues jobs
  4. Notifications:
    • Workers process webhook notification to merchant
    • Workers send confirmation emails

​
Deployment Guidelines

​
SDK Deployment

# Build the package
npm run build

# Update version in package.json
npm version patch

# Publish to npm
npm publish

​
Payment Gateway Deployment

The Payment Gateway is a Next.js application that can be deployed to Vercel, Netlify, or any Node.js hosting: 
# Build for production
npm run build

# For Vercel
vercel deploy

# For custom hosting
npm start

​
Workers Deployment

Workers should be deployed as a separate service: 
# Build for production
npm run build

# Start in production mode
npm start
For production, use PM2 or Docker as described in the Workers Setup guide.

​
Debugging Tips

​
SDK Debugging

  • Set localStorage.debug = 'whiskypay:*' in the browser console to enable debug logging
  • Use the browser developer tools to inspect network requests and responses
  • Check the console for detailed error messages

​
Payment Gateway Debugging

  • Check the Next.js server logs for API errors
  • Verify Supabase connection and queries
  • Use the /api/debug endpoint (in development) to check system status

​
Workers Debugging

  • Check Redis connection status
  • Verify job queues are being populated
  • Examine worker logs for processing errors
  • Use BullMQ’s API to inspect job status

​
Contributing Guidelines

  1. Branch Management:
    • main: Production-ready code
    • develop: Integration branch for features
    • feature/[name]: Individual features
  2. Pull Request Process:
    • Create feature branches from develop
    • Submit PRs back to develop
    • Ensure tests pass
    • Follow code style guidelines
  3. Versioning:
    • Follow semantic versioning (MAJOR.MINOR.PATCH)
    • Document breaking changes in CHANGELOG.md

​
Resources