Create checkout programmatically

Creates a checkout session for a price point and customer, and renders the payment UI in your container. This is the primary method to start a subscription checkout.

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

Parameters

string

required

Your organization ID. The TypeScript types require it. In JavaScript, you can leave it out after you call configure().

string

required

The price point identifier.

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.

string

required

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

Show container styling requirements

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

Per-call API settings: baseUrl and region. These override the values from configure().

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']. In TypeScript, use the PaymentMethod enum, such as PaymentMethod.APPLE_PAY.

object

Cardholder name and email field options. Learn more about the card form.

object

Apple Pay button options. The drop-in checkout applies only buttonType. Learn more about Apple Pay button types.

object

Styles for the card number, expiry, and CVV inputs. Learn more about card input styles.

Callbacks

All callbacks are optional.

() => void

Called when the checkout has been initialized and is ready.

(result: PaymentResult) => void

Called when the payment succeeds. An alternative to the 'success' event.

(error?: Error) => void

Called when the checkout fails to initialize or a price update fails. An alternative to the 'error' event.It’s also called with no argument when the buyer selects a payment method or starts a payment, so you can clear an error message. Payment declines don’t call it. Learn more about the error event.

(newState, oldState) => void

Called on every state change. An alternative to the 'status-change' event.

() => void

Called when the checkout is destroyed. An alternative to the 'destroy' event.

(info: TaxInfo) => void

Called with the total and tax when FunnelFox Payments Taxes is on.

() => void

Called when the buyer changes their country or zip code and a tax recalculation starts.

(error: Error) => void

Called when a tax recalculation fails.

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. If the checkout can’t initialize, the promise rejects and the SDK replaces the container’s content with an error message that shows the request ID. Learn more about error handling.

Example

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

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

  // Optional
  clientMetadata: { source: 'web' },
  paymentMethodOrder: ['APPLE_PAY', 'GOOGLE_PAY', 'PAYPAL', 'PAYMENT_CARD'],
  applePay: { buttonType: 'subscribe' },

  // Callbacks (alternative to events)
  onInitialized: () => {
    /* ... */
  },
  onSuccess: result => {
    /* ... */
  },
  onError: error => {
    /* error is undefined when a new payment starts */
  },
  onStatusChange: (state, oldState) => {
    /* ... */
  },
  onTaxChange: info => {
    /* update your price display */
  },
});

API reference

Webhook reference

Billing Web SDK

Create checkout programmatically

Parameters

Callbacks

Returns

Example

​Parameters

​Callbacks

​Returns

​Example

Parameters

Callbacks

Returns

Example