Create checkout programmatically

Creates and opens a new checkout session for a given price and customer, and renders the payment UI on the page. This is the primary method to initiate a subscription checkout.

You can customize the checkout appearance and styles. Learn more about checkout customization.

Parameters

string

required

Your organization ID, if not already configured globally. Useful if you did not call configure() or need to override it for this checkout.

string

required

The price identifier for the subscription or product.

object

required

Customer information.

Show customer properties

string

required

Your internal identifier for the user.

string

required

Customer’s email address.

string

ISO country code for the customer (if applicable).

string

required

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

Show container styling requirements

When using the default skin, the container element must have the following CSS properties for proper display of the loading indicator:

#checkout-container {
  position: relative;
  min-height: 200px; /* Adjust based on your layout */
}

position: relative: Required because the loading overlay uses position: absolute to cover the container
min-height: Required to ensure the loader is visible during initialization. Recommended minimum is 200px

object

Additional metadata to associate with this checkout or customer. This data will be passed through to your backend.

object

Custom CSS selectors for card input fields. If not provided, FunnelFox will auto-generate the payment form.

Show Card selector properties

string

required

CSS selector for an empty <div> where the hosted card number input is injected.

string

required

CSS selector for an empty <div> for the hosted expiry input.

string

required

CSS selector for an empty <div> for the hosted CVV input.

string

required

CSS selector for a <button> element. The SDK hooks its click event for form submission.

string

CSS selector for an <input> element. The SDK reads its value directly.

string

CSS selector for an <input> element. The SDK reads its value directly.

object

Custom CSS selectors for payment buttons. Resolved relative to document, not the container.

Show Payment button selector properties

string

required

CSS selector for a <div> where the PayPal button is rendered.

string

required

CSS selector for a <div> where the Google Pay button is rendered.

string

required

CSS selector for a <div> where the Apple Pay button is rendered.

array

Array of payment method identifiers to control the display order. Available values: 'PAYMENT_CARD', 'PAYPAL', 'GOOGLE_PAY', 'APPLE_PAY'. Defaults to ['APPLE_PAY', 'GOOGLE_PAY', 'PAYPAL', 'PAYMENT_CARD'].

function

Callback invoked when the checkout has been initialized and is ready.

function

Callback to execute when the payment is successful. An alternative to listening for the 'success' event.

function

Callback for handling errors. Alternative to the 'error' event.

function

Callback invoked on every status change. Alternative to the 'status-change' event.

Returns

A Promise<CheckoutInstance> that resolves to a CheckoutInstance object representing the checkout session. You can use this object to monitor events or perform actions on the active checkout.

Example

import { createCheckout } from '@funnelfox/billing';

const checkout = await createCheckout({
  // Required
  priceId: 'price_123',
  customer: {
    externalId: 'user_456',
    email: 'user@example.com',
    countryCode: 'US', // Optional
  },
  container: '#checkout-container',

  // Optional
  orgId: 'your-org-id', // If not configured globally
  clientMetadata: { source: 'web' },
  cardSelectors: {
    // Custom card input selectors (optional, defaults to auto-generated)
    cardNumber: '#cardNumberInput',
    expiryDate: '#expiryInput',
    cvv: '#cvvInput',
    cardholderName: '#cardHolderInput',
    emailAddress: '#emailInput',
    button: '#submitButton',
  },
  paymentButtonSelectors: {
    paypal: '#paypalButton',
    googlePay: '#googlePayButton',
    applePay: '#applePayButton',
  },
  paymentMethodOrder: ['APPLE_PAY', 'GOOGLE_PAY', 'PAYPAL', 'PAYMENT_CARD'], // Optional

  // Callbacks (alternative to events)
  onInitialized: () => {
    /* ... */
  },
  onSuccess: result => {
    /* ... */
  },
  onError: error => {
    /* ... */
  },
  onStatusChange: (state, oldState) => {
    /* ... */
  },
});

API reference

Webhook reference

Billing Web SDK

Create checkout programmatically

Parameters

Returns

Example

​Parameters

​Returns

​Example

Parameters

Returns

Example