Skip to main content

Table of Contents

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 the payable.http() adapter:
That’s it! The endpoint is now protected. The paywall will:
  • 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 one payable handler and apply it to all protected endpoints:
Plans are managed on the product in SolvaPay Console. Customers select a plan during activation and the SDK resolves the correct plan from their purchase automatically.

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, so payable.http() never takes the customer from a header on its own. Pick one of these. 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

Without getCustomerRef, payable.http() reads Authorization: Bearer <token> and trusts it only when it can verify it:
  • HS256: SOLVAPAY_JWT_SECRET (or SUPABASE_JWT_SECRET)
  • ES256 / RS256: SOLVAPAY_JWKS_URL (derived from SUPABASE_URL on Supabase)
The token’s 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 sets x-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 a formatGate 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

Use paywall.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:
The allow result carries:
  • customerRef — the resolved customer (from getCustomerRef, else a verified bearer token)
  • trackSuccess(opts?) / trackFail(error, opts?) — fire-and-forget usage reporting; call exactly one of them after the stream finishes
  • decision — the underlying paywall decision, if you need plan details
Options: 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

  1. Extract Customer Reference Early: Use middleware to extract and validate customer references before they reach protected endpoints.
  2. Handle Paywall Errors Gracefully: Provide clear error messages and checkout URLs to users.
  3. Use Environment Variables: Store API keys and configuration in environment variables.
  4. Separate Business Logic: Keep your business logic functions separate from route handlers for better testability.
  5. Type Safety: Use TypeScript for better type safety and developer experience.
  6. Error Logging: Log errors appropriately for debugging while keeping sensitive information secure.

Next Steps