Skip to content

Web SDK quickstart guide

Get started with the FunnelFox Payments Web SDK: install it, choose an integration, and render your first checkout.

The FunnelFox Payments Web SDK connects your paywall page to FunnelFox Payments Subscription Billing. It renders the checkout through Primer’s Headless Checkout or through Stripe directly, and creates the subscription when the payment succeeds.

  • Type-safe: Complete TypeScript definitions ship with the package.
  • Dynamic pricing: Switch the price point without reloading the page.
  • Event-driven: Handle success, errors, and state changes with events or callbacks.
  • Taxes: Get the total with tax as the buyer’s location changes.
  • Decline codes: Tell an insufficient-funds decline apart from other failures.
  • On-demand loading: The SDK loads Primer and Stripe only when a checkout needs them.
  • Browser support: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+. Internet Explorer is not supported.

The SDK offers three ways to build a checkout:

The steps below use the drop-in checkout.

Install the SDK from a CDN or from npm.

Include the SDK script. It adds a global Billing object to the page:

<script src="https://unpkg.com/@funnelfox/billing@0.11.0/dist/funnelfox-billing.min.js"></script>

You don’t need to add Primer’s scripts to the page. The SDK loads Primer v2.57.3 from sdk.primer.io when a checkout needs it.

Create a checkout for a price point and a customer, and render it on your page:

import { createCheckout } from '@funnelfox/billing';
await createCheckout({
orgId: 'your-org-id',
priceId: 'price_123',
customer: {
externalId: 'user_456',
email: 'user@example.com',
},
container: '#checkout-container',
});

Required parameters:

orgIdstringrequired
priceIdstringrequired

The price point identifier.

customerobjectrequired

Customer information (requires externalId and email).

containerstringrequired

A CSS selector for the DOM element where the checkout form will be mounted.

After you call createCheckout(), the checkout form appears in the container, ready for the buyer to pay.