Table of Contents
- Installation
- Basic Setup
- Protecting Endpoints
- Authentication Integration
- Error Handling
- Advanced Usage
- Complete Example
Installation
Install the required packages:Basic Setup
1. Initialize SolvaPay
Create a SolvaPay instance in your Express app:2. Protect Your First Endpoint
Wrap your business logic with thepayable.http() adapter:
- Check if the customer has a valid purchase
- Track usage and enforce limits
- Return a paywall error with checkout URL if needed
Protecting Endpoints
Multiple Endpoints
Create onepayable handler and apply it to all protected endpoints:
Accessing Request Data
The HTTP adapter passes the Express request object to your business logic:Authentication Integration
SolvaPay needs to know which customer is calling. A browser or API client can send any header, sopayable.http() never takes the customer from a header on its own. Pick one of these.
Option 1: getCustomerRef from your own auth (recommended)
Return the user your auth middleware already verified. SolvaPay finds or creates the customer for that id:
getCustomerRef may return your user id or a SolvaPay customer ref (cus_…) you stored. An empty string means anonymous.
Option 2: Verified bearer tokens
WithoutgetCustomerRef, payable.http() reads Authorization: Bearer <token> and trusts it only when it can verify it:
- HS256:
SOLVAPAY_JWT_SECRET(orSUPABASE_JWT_SECRET) - ES256 / RS256:
SOLVAPAY_JWKS_URL(derived fromSUPABASE_URLon Supabase)
sub is your user id. It is always looked up by externalRef, never taken as a customer ref, even when it starts with cus_. A token nothing can verify gets a 401.
Option 3: Behind a gateway you trust
If a gateway setsx-customer-ref on every request and nothing reaches your server without passing it, set SOLVAPAY_AUTH_TRUST_GATEWAY=true. Without that, a request carrying x-customer-ref gets a 401, so a client can’t name another customer.
A request with none of these is anonymous.
Error Handling
Basic Error Handling
The HTTP adapter routes paywall gate outcomes through aformatGate
channel that emits a 402 response with the standard JSON body
({success:false, error, product, checkoutUrl, message, ...}). Merchants
don’t need to catch anything for the happy path:
Custom Paywall Responses
Usepaywall.decide() directly when you want full control over the
402 response shape (e.g. a hand-rolled route that doesn’t use
payable.http()):
Legacy PaywallError Compat
Consumers that still try/catch a PaywallError keep working —
PaywallError is exported as a compat shim for merchant code that
throws from deep inside business logic:
Advanced Usage
Custom Customer Reference Extraction
Override customer reference extraction per endpoint:Response Transformation
Transform responses before sending:Streaming Responses with payable.gate()
payable.http() owns the whole response, which doesn’t fit streaming or SSE endpoints. For those,
use payable.gate() — it returns a decision instead of wrapping a handler, so you keep full
control of the response and report usage yourself:
allow result carries:
customerRef— the resolved customer (fromgetCustomerRef, else a verified bearer token)trackSuccess(opts?)/trackFail(error, opts?)— fire-and-forget usage reporting; call exactly one of them after the stream finishesdecision— the underlying paywall decision, if you need plan details
getCustomerRef(req) overrides customer resolution, and ctx accepts a
Workers-style waitUntil so tracking outlives the response on edge runtimes. See
examples/chat-checkout-demo in the SDK repo for a complete SSE chat endpoint built on
payable.gate().
Response Formatting
The HTTP adapter automatically formats responses. Your business logic should return:- Object: Sent as JSON with 200 status
- Error: Thrown as exception (PaywallError handled automatically)
Complete Example
Here’s a complete Express.js application with SolvaPay integration:Testing the Example
Best Practices
- Extract Customer Reference Early: Use middleware to extract and validate customer references before they reach protected endpoints.
- Handle Paywall Errors Gracefully: Provide clear error messages and checkout URLs to users.
- Use Environment Variables: Store API keys and configuration in environment variables.
- Separate Business Logic: Keep your business logic functions separate from route handlers for better testability.
- Type Safety: Use TypeScript for better type safety and developer experience.
- Error Logging: Log errors appropriately for debugging while keeping sensitive information secure.
Next Steps
- Next.js Integration Guide - Learn how to integrate with Next.js
- Webhooks - Handle async purchase and subscription events
- Custom Authentication Adapters - Build custom auth adapters
- API Reference - Full API documentation