Error handling

The Checkout Components provide errors in two ways:

• Thrown errors during initialization — these are programming errors that should be fixed during development
• Returned errors from submit() and confirmPayment() — these are runtime errors that should be handled in your code

Initialization errors

Initialization errors are thrown when initializing the SDK incorrectly. Wrap your initialization code in a try-catch during development to catch configuration issues.

try {
    const rootline = new Rootline({ locale: "invalid" });
    const components = rootline.components("checkout", {
        paymentSessionSecret: "pss_..."
    });
} catch (error) {
    console.error("Initialization error:", error.message);
}

Error	Cause
Components must be initialized with either paymentSessionSecret or accountPublishableKey	Missing required credentials
When using accountPublishableKey, both 'amount' and 'currency' are required	Deferred flow missing amount or currency
Cannot use both 'paymentSessionSecret' and 'accountPublishableKey'	Mixed initialization modes
Invalid RootlineOptions	Invalid options like unsupported locale
Mount target not found	The DOM element passed to mount() doesn't exist

Runtime errors

Both components.submit() and rootline.confirmPayment() return an error object when something goes wrong. Errors have a code for programmatic handling and a localized message for display to customers.

const { error } = await components.submit();

if (error) {
    console.error(error.code, error.message);
    // Display error.message to the customer
}

Submit errors

These errors can be returned by components.submit():

Code	Description
INVALID_FORM_DATA	Form validation failed — fields are incomplete or invalid.
NO_PAYMENT_METHOD	No payment method selected or payment details not provided.
NO_COMPONENTS	No components available to submit.
SUBMISSION_FAILED	Submission failed.
CARD_ENCRYPTION_FAILED	Failed to encrypt card details.
APPLE_PAY_CANCELLED	Customer cancelled the Apple Pay payment.
GOOGLE_PAY_CANCELLED	Customer cancelled the Google Pay payment.

Confirm errors

These errors can be returned by rootline.confirmPayment():

Code	Description
MISSING_COMPONENTS	Components argument is required but not provided.
INVALID_COMPONENTS	The components argument is not a valid Components object.
INVALID_RETURN_URL	The returnUrl provided is not a valid URL.
MISSING_URL	Payment action requires a redirect URL.
INVALID_CARD_DETAILS	Card details are invalid.
MISSING_PAYMENT_SESSION_SECRET	Payment session secret was not provided when making the confirmPayment() call in the deferred flow.
INVALID_ARGUMENTS	Required arguments are missing.
COMPONENT_ERROR	Component not available.
NO_COMPONENTS	No components available.
CONFIRMATION_FAILED	Payment confirmation failed. Retry confirmPayment()
PAYMENT_FAILED	Payment failed — The customer can try another payment. You need to create a new payments request.
APPLE_PAY_MERCHANT_VALIDATION_FAILED	Apple Pay merchant validation failed.
APPLE_PAY_AUTHORIZATION_FAILED	Apple Pay payment authorization failed.
GOOGLE_PAY_LOAD_FAILED	Failed to load Google Pay.
GOOGLE_PAY_AUTHORIZATION_FAILED	Google Pay payment authorization failed.

Displaying errors to customers

Error messages are localized based on the locale option and are suitable for display to customers. For validation errors in the Card Form, the SDK automatically displays inline error messages — you only need to handle errors returned by submit() and confirmPayment().

const { error } = await components.submit();

if (error) {
    // Show the localized message to the customer
    document.getElementById("error-message").textContent = error.message;
    return;
}