SolvaPay

SolvaPay SDK v1.0.0

---

SolvaPay SDK / server/src / SolvaPay

Interface: SolvaPay

Defined in: packages/server/src/factory.ts:197

SolvaPay instance with payable method and common API methods.

This interface provides the main API for interacting with SolvaPay. Use createSolvaPay() to create an instance.

Example

const solvaPay = createSolvaPay();

// Create payable handlers
  * const payable = solvaPay.payable({ product: 'prd_myapi', plan: 'pln_premium' });
  *
  * // Manage customers
  * const customerRef = await solvaPay.ensureCustomer('user_123', 'user_123', {
  *   email: 'user@example.com'
  * });
  *
  * // Create payment intents
  * const intent = await solvaPay.createPaymentIntent({
  *   productRef: 'prd_myapi',
  *   planRef: 'pln_premium',
  *   customerRef: 'user_123'
  * });

Properties

apiClient

apiClient: SolvaPayClient

Defined in: packages/server/src/factory.ts:519

Direct access to the API client for advanced operations.

Use this for operations not exposed by the SolvaPay interface, such as product/plan management or custom API calls.

Example

// Access API client directly for custom operations
const products = await solvaPay.apiClient.listProducts();

Methods

checkLimits()

checkLimits(params): Promise<{ checkoutUrl?: string; plan: string; remaining: number; withinLimits: boolean; }>

Defined in: packages/server/src/factory.ts:348

Check if customer is within usage limits for a product.

This method checks purchase status and usage limits without executing business logic. Use payable() for automatic protection.

Parameters

params

Limit check parameters

customerRef

string

Customer reference

productRef

string

Product reference

Returns

Promise<{ checkoutUrl?: string; plan: string; remaining: number; withinLimits: boolean; }>

Limit check result with remaining usage and checkout URL if needed

Example

const limits = await solvaPay.checkLimits({
  customerRef: 'user_123',
  productRef: 'prd_myapi'
});

if (!limits.withinLimits) {
  // Redirect to checkout
  window.location.href = limits.checkoutUrl;
}

---

createCheckoutSession()

createCheckoutSession(params): Promise<{ checkoutUrl: string; sessionId: string; }>

Defined in: packages/server/src/factory.ts:472

Create a hosted checkout session for a customer.

This creates a Stripe Checkout session that redirects the customer to a hosted payment page. After payment, customer is redirected back.

Parameters

params

Checkout session parameters

customerRef

string

Customer reference

planRef?

string

Optional plan reference (if not specified, shows plan selector)

productRef

string

Product reference

returnUrl?

string

URL to redirect to after successful payment

Returns

Promise<{ checkoutUrl: string; sessionId: string; }>

Checkout session with redirect URL

Example

const session = await solvaPay.createCheckoutSession({
  productRef: 'prd_myapi',
  customerRef: 'user_123',
  planRef: 'pln_premium',
  returnUrl: 'https://myapp.com/success'
});

// Redirect customer to checkout
window.location.href = session.checkoutUrl;

---

createCustomer()

createCustomer(params): Promise<{ customerRef: string; }>

Defined in: packages/server/src/factory.ts:415

Create a new customer in SolvaPay backend.

Note: ensureCustomer() is usually preferred as it's idempotent. Use this only if you need explicit control over customer creation.

Parameters

params

Customer creation parameters

email

string

Customer email address (required)

name?

string

Optional customer name

Returns

Promise<{ customerRef: string; }>

Created customer reference

Example

const { customerRef } = await solvaPay.createCustomer({
  email: 'user@example.com',
  name: 'John Doe'
});

---

createCustomerSession()

createCustomerSession(params): Promise<{ customerUrl: string; sessionId: string; }>

Defined in: packages/server/src/factory.ts:502

Create a customer portal session for managing purchases.

This creates a Stripe Customer Portal session that allows customers to manage their purchases, update payment methods, and view invoices.

Parameters

params

Customer session parameters

customerRef

string

Customer reference

Returns

Promise<{ customerUrl: string; sessionId: string; }>

Customer portal session with redirect URL

Example

const session = await solvaPay.createCustomerSession({
  customerRef: 'user_123'
});

// Redirect customer to portal
window.location.href = session.customerUrl;

---

createPaymentIntent()

createPaymentIntent(params): Promise<{ accountId?: string; clientSecret: string; id: string; publishableKey: string; }>

Defined in: packages/server/src/factory.ts:277

Create a Stripe payment intent for a customer to purchase a plan.

This creates a payment intent that can be confirmed on the client side using Stripe.js. After confirmation, call processPaymentIntent() to complete the purchase.

Parameters

params

Payment intent parameters

customerRef

string

Customer reference

idempotencyKey?

string

Optional idempotency key for retry safety

planRef

string

Plan reference to purchase

productRef

string

Product reference

Returns

Promise<{ accountId?: string; clientSecret: string; id: string; publishableKey: string; }>

Payment intent with client secret and publishable key

Example

const intent = await solvaPay.createPaymentIntent({
  productRef: 'prd_myapi',
  planRef: 'pln_premium',
  customerRef: 'user_123',
  idempotencyKey: 'unique-key-123'
});

// Use intent.clientSecret with Stripe.js on client

---

ensureCustomer()

ensureCustomer(customerRef, externalRef?, options?): Promise<string>

Defined in: packages/server/src/factory.ts:245

Ensure customer exists in SolvaPay backend (idempotent).

Creates a customer if they don't exist, or returns existing customer reference. This is automatically called by the paywall system, but you can call it explicitly for setup or testing.

Parameters

customerRef

string

The customer reference used as a cache key (e.g., Supabase user ID)

externalRef?

string

Optional external reference for backend lookup (e.g., Supabase user ID). If provided, will lookup existing customer by externalRef before creating new one. The externalRef is stored on the SolvaPay backend for customer lookup.

options?

Optional customer details for customer creation

email?

string

Customer email address

name?

string

Customer name

Returns

Promise<string>

Customer reference (backend customer ID)

Example

// Ensure customer exists before processing payment
const customerRef = await solvaPay.ensureCustomer(
  'user_123',           // customerRef (your user ID)
  'user_123',           // externalRef (same or different)
  {
    email: 'user@example.com',
    name: 'John Doe'
  }
);

---

getCustomer()

getCustomer(params): Promise<CustomerResponseMapped>

Defined in: packages/server/src/factory.ts:441

Get customer details including purchases and usage.

Returns full customer information from the SolvaPay backend, including all active purchases, usage history, and customer metadata.

Parameters

params

Customer lookup parameters

customerRef?

string

Optional customer reference (SolvaPay ID)

externalRef?

string

Optional external reference (e.g., Supabase ID)

Returns

Promise<CustomerResponseMapped>

Customer details with purchases and metadata

Example

// Lookup by SolvaPay customer ID
const customer = await solvaPay.getCustomer({
  customerRef: 'cust_123'
});

// Lookup by external ID (e.g. Supabase user ID)
const customer = await solvaPay.getCustomer({
  externalRef: 'user_123'
});

---

payable()

payable(options?): PayableFunction

Defined in: packages/server/src/factory.ts:214

Create a payable handler with explicit adapters for different frameworks.

Parameters

options?

PayableOptions

Payable options including product and plan references

Returns

PayableFunction

PayableFunction with framework-specific adapters

Example

const payable = solvaPay.payable({
  product: 'prd_myapi',
  plan: 'pln_premium'
});

app.post('/tasks', payable.http(createTask));

---

processPaymentIntent()

processPaymentIntent(params): Promise<ProcessPaymentResult>

Defined in: packages/server/src/factory.ts:317

Process a payment intent after client-side Stripe confirmation.

Creates the purchase immediately, eliminating webhook delay. Call this after the client has confirmed the payment intent with Stripe.js.

Parameters

params

Payment processing parameters

customerRef

string

Customer reference

paymentIntentId

string

Stripe payment intent ID from client confirmation

planRef?

string

Optional plan reference (if not in payment intent)

productRef

string

Product reference

Returns

Promise<ProcessPaymentResult>

Payment processing result with purchase details

Example

// After client confirms payment with Stripe.js
const result = await solvaPay.processPaymentIntent({
  paymentIntentId: 'pi_1234567890',
  productRef: 'prd_myapi',
  customerRef: 'user_123',
  planRef: 'pln_premium'
});

if (result.success) {
  console.log('Purchase created:', result.purchase);
}

---

trackUsage()

trackUsage(params): Promise<void>

Defined in: packages/server/src/factory.ts:385

Track usage for a customer action.

This is automatically called by the paywall system. You typically don't need to call this manually unless implementing custom tracking.

Parameters

params

Usage tracking parameters

action?

string

Optional action name for analytics

actionDuration

number

Action duration in milliseconds

customerRef

string

Customer reference

outcome

"success" | "paywall" | "fail"

Action outcome ('success', 'paywall', or 'fail')

planRef

string

Plan reference

productRef

string

Product reference

requestId

string

Unique request ID

timestamp

string

ISO timestamp of the action

Returns

Promise<void>

Example

await solvaPay.trackUsage({
  customerRef: 'user_123',
  productRef: 'prd_myapi',
  planRef: 'pln_premium',
  outcome: 'success',
  action: 'api_call',
  requestId: 'req_123',
  actionDuration: 150,
  timestamp: new Date().toISOString()
});