Skip to main content

Core Concepts

Understanding the key concepts in SolvaPay SDK will help you build effective monetization strategies.

Table of Contents​

Agents and Plans​

Agents​

An Agent represents your API, service, or application that you want to monetize. Each agent has:

  • Agent Reference (agt_...) - Unique identifier for your agent
  • Name - Human-readable name
  • Description - What the agent does

Agents are created in the SolvaPay dashboard and represent the service you're protecting.

// All endpoints for this agent share the same paywall rules
const payable = solvaPay.payable({
  agent: 'agt_myapi', // Your agent reference
})

Plans​

A Plan represents a purchase tier or pricing model. Plans define:

  • Plan Reference (pln_...) - Unique identifier for the plan
  • Name - Plan name (e.g., "Premium", "Pro")
  • Price - Purchase price
  • Usage Limits - What's included (e.g., 1000 API calls/month)
  • Features - What features are available

Plans are created in the SolvaPay dashboard and can be associated with agents.

// Protect endpoints with a specific plan requirement
const payable = solvaPay.payable({
  agent: 'agt_myapi',
  plan: 'pln_premium', // Users need this plan to access
})

Agent-Plan Relationship​

  • One agent can have multiple plans - Different tiers (Free, Pro, Enterprise)
  • Plans can be shared across agents - Reuse plans for multiple services
  • Paywall checks - Verify user has the required plan for the agent

Customer References​

What is a Customer Reference?​

A Customer Reference (customerRef) is a unique identifier for a user in your system. It's used to:

  • Track usage per customer
  • Check purchase status
  • Enforce usage limits
  • Create payment intents

How Customer References Work​

  1. Customer Creation: When a user first interacts with your protected endpoints, SolvaPay automatically creates a customer record
  2. External Reference: You can link SolvaPay customers to your user IDs using externalRef
  3. Customer Lookup: SolvaPay uses the customer reference to check purchases and track usage
// Ensure customer exists (creates if doesn't exist)
const customerRef = await solvaPay.ensureCustomer(
  'user_123', // customerRef (your user ID)
  'user_123', // externalRef (same or different)
  {
    email: 'user@example.com',
    name: 'John Doe',
  },
)

Customer Reference in Requests​

For HTTP adapters, pass the customer reference via headers:

// Express.js example
app.post(
  '/tasks',
  payable.http(async req => {
    const customerRef = req.headers['x-customer-ref']
    // Business logic here
  }),
)

For Next.js, the customer reference is automatically extracted from authentication:

// Next.js automatically extracts from auth middleware
const result = await checkPurchase(request)
// result.customerRef is automatically set

Paywall Protection Flow​

How Paywall Protection Works​

When you wrap your business logic with payable(), SolvaPay automatically:

  1. Extracts Customer Reference - From headers, auth tokens, or request context
  2. Checks Purchase Status - Verifies if customer has required plan
  3. Checks Usage Limits - Verifies if customer is within usage limits
  4. Executes Business Logic - If checks pass, runs your function
  5. Tracks Usage - Records the usage for billing/analytics
  6. Returns Paywall Error - If checks fail, returns error with checkout URL

Paywall Flow Diagram​

Request → Extract Customer Ref → Check Purchase
                                    ↓
                              Has Purchase?
                                    ↓
                              Yes → Check Usage Limits
                                    ↓
                              Within Limits?
                                    ↓
                              Yes → Execute Business Logic
                                    ↓
                              Track Usage → Return Result
                                    ↓
                              No → Return Paywall Error
                                    ↓
                              (with checkout URL)

Paywall Error Response​

When a paywall is triggered, SolvaPay returns a structured error:

{
  error: 'PaywallError',
  message: 'Purchase required',
  checkoutUrl: 'https://checkout.solvapay.com/...',
  // Additional metadata for custom UI
}

You can customize the error handling:

try {
  const result = await handler(req)
  return result
} catch (error) {
  if (error instanceof PaywallError) {
    // Custom paywall handling
    return res.status(402).json({
      error: error.message,
      checkoutUrl: error.checkoutUrl,
    })
  }
  throw error
}

Purchase Lifecycle​

Purchase States​

Purchases can be in different states:

  • Active - Purchase is active and can be used
  • Cancelled - Purchase is cancelled but still active until end date
  • Expired - Purchase has expired
  • Past Due - Payment failed, purchase is past due

Purchase Management​

// Check purchase status
const customer = await solvaPay.getCustomer({ customerRef: 'user_123' })
const purchases = customer.purchases

// Cancel renewal
await solvaPay.cancelRenewal({
  customerRef: 'user_123',
  purchaseRef: 'sub_...',
})

Free Tier​

All agents support a free tier with limited usage:

  • Free Tier Limits - Set in SolvaPay dashboard (e.g., 100 calls/month)
  • No Purchase Required - Free tier works without payment
  • Automatic Upgrade Prompt - When limits are exceeded, users see checkout URL

Authentication Flow​

How Authentication Works​

SolvaPay SDK integrates with your existing authentication system:

  1. Extract User ID - From auth tokens, headers, or session
  2. Map to Customer Reference - User ID becomes customer reference
  3. Sync Customer Data - Email, name, etc. synced to SolvaPay
  4. Check Purchase - Verify purchase status

Authentication Adapters​

SolvaPay provides adapters for common auth systems:

// Supabase adapter
import { SupabaseAuthAdapter } from '@solvapay/auth/supabase'

const adapter = new SupabaseAuthAdapter({
  supabaseUrl: process.env.SUPABASE_URL,
  supabaseKey: process.env.SUPABASE_ANON_KEY,
})

// Extract user ID from Supabase JWT
const userId = adapter.getUserId(request)

Next.js Authentication​

Next.js helpers automatically extract user info:

import { getAuthenticatedUser } from '@solvapay/next'

// Automatically extracts userId, email, name from Supabase JWT
const user = await getAuthenticatedUser(request)
// { userId: '...', email: '...', name: '...' }

Usage Tracking​

Automatic Usage Tracking​

SolvaPay automatically tracks usage when you use payable():

  • Per Request - Each protected request is tracked
  • Per Customer - Usage is tracked per customer reference
  • Per Agent - Usage is tracked per agent
  • Per Plan - Usage limits are enforced per plan

Manual Usage Tracking​

You can also track usage manually:

// Track custom usage
await solvaPay.trackUsage({
  customerRef: 'user_123',
  agentRef: 'agt_myapi',
  amount: 1, // Usage amount
  metadata: {
    /* custom data */
  },
})

Usage Limits​

Usage limits are enforced automatically:

  • Plan Limits - Set in SolvaPay dashboard
  • Free Tier Limits - Automatic for all customers
  • Custom Limits - Can be set per customer

Next Steps​