Skip to content

Create checkout programmatically

Render a drop-in checkout for a price point and customer, and handle the payment result.

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.

orgIdstringrequired

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

priceIdstringrequired

The price point identifier.

customerobjectrequired

Customer information.

customer properties
externalIdstringrequired

Your internal identifier for the user.

emailstringrequired

Customer’s email address.

countryCodestring

ISO country code for the customer.

containerstringrequired

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

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
clientMetadataobject

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

apiConfigobject

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

paymentMethodOrderarray

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.

cardobject

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

applePayobject

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

styleobject

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

All callbacks are optional.

onInitialized() => void

Called when the checkout has been initialized and is ready.

onSuccess(result: PaymentResult) => void

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

onError(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.

onStatusChange(newState, oldState) => void

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

onDestroy() => void

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

onTaxChange(info: TaxInfo) => void

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

onTaxPending() => void

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

onTaxError(error: Error) => void

Called when a tax recalculation fails.

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.

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 */
},
});