Your organization ID. The TypeScript types require it. In JavaScript, you can leave it out after you call configure().
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.
Parameters
Section titled “Parameters”orgIdstringrequiredpriceIdstringrequiredThe price point identifier.
customerobjectrequiredCustomer information.
customer properties
externalIdstringrequiredYour internal identifier for the user.
emailstringrequiredCustomer’s email address.
countryCodestringISO country code for the customer.
containerstringrequiredA 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 usesposition: absoluteto cover the containermin-height: Required to ensure the loader is visible during initialization. Recommended minimum is200px
clientMetadataobjectAdditional metadata to associate with this checkout or customer. This data will be passed through to your backend.
apiConfigobjectPer-call API settings: baseUrl and region. These override the values
from configure().
paymentMethodOrderarrayArray 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.
cardobjectCardholder name and email field options. Learn more about the card form.
applePayobjectApple Pay button options. The drop-in checkout applies only buttonType.
Learn more about
Apple Pay button types.
styleobjectStyles for the card number, expiry, and CVV inputs. Learn more about card input styles.
Callbacks
Section titled “Callbacks”All callbacks are optional.
onInitialized() => voidCalled when the checkout has been initialized and is ready.
onSuccess(result: PaymentResult) => voidCalled when the payment succeeds. An alternative to the 'success' event.
onError(error?: Error) => voidCalled 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) => voidCalled on every state change. An alternative to the 'status-change' event.
onDestroy() => voidCalled when the checkout is destroyed. An alternative to the 'destroy'
event.
onTaxChange(info: TaxInfo) => voidCalled with the total and tax when FunnelFox Payments Taxes is on.
onTaxPending() => voidCalled when the buyer changes their country or zip code and a tax recalculation starts.
onTaxError(error: Error) => voidCalled when a tax recalculation fails.
Returns
Section titled “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
Section titled “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 */ },});