Error handling

The Checkout Components provide errors in two ways:

• Thrown errors during initialization and argument validation — 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
• Cancellations from submit() and confirmPayment() — the customer closed the payment sheet

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
confirmPayment() requires a 'components' argument	Missing components in confirmPayment() call
The 'components' argument is not a valid Components instance	Invalid object passed as components
The 'returnUrl' is not a valid URL	Invalid URL format for returnUrl
A paymentSessionSecret is required	Missing payment session secret in deferred flow

Runtime errors

Both components.submit() and rootline.confirmPayment() return an error object when something goes wrong. Each error has three fields:

• code — a short string for programmatic handling (e.g. validation_error, payment_failed)
• reason — a more specific diagnostic string (e.g. card_encryption_failed, apple_pay_authorization_failed). This is not intended for display to customers, but can be useful in your own logging and support tools.
• message — a localized, customer-facing message you can display directly

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

if (error) {
    console.log(error.code, error.reason); // for your logs
    document.getElementById("error-message").textContent = error.message; // for the customer
}

Cancellations

When a customer closes a payment sheet (e.g. Apple Pay or Google Pay), the response contains cancelled: true instead of an error. This is not an error — the customer can simply try again.

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

if (cancelled) {
    // Customer closed the payment sheet — they can try again
    return;
}

Error codes

Both submit() and confirmPayment() return from the same set of error codes:

Code	What happened	What to do
validation_error	Customer input is incomplete or invalid.	Display error.message. The SDK also shows inline field errors automatically.
sdk_error	Something went wrong before the payment could be processed.	Display error.message. The customer can start a new payment attempt. If the issue persists, contact Rootline support.
network_error	Could not reach the payment server.	Display error.message. The customer can retry. See Network errors below.
payment_failed	The payment was processed but declined or the payment method is unavailable.	Display error.message. Create a new payment and let the customer try another payment method.

Network errors

A network_error means the SDK could not reach the Rootline payment server. The SDK already retries failed requests internally for up to 30 seconds before returning this error, so by the time your code sees it, the issue has persisted for a while.

This is most often caused by the customer's internet connection — for example unstable Wi-Fi, mobile network, or VPN/tunnel connections. In rare cases, it may indicate a Rootline service disruption — you can check status.rootline.com for ongoing incidents.

The customer can safely retry the same payment when they see this error.

Handling errors

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

Here is a generic pattern for handling all errors:

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

if (cancelled) {
    // Customer closed the payment sheet (e.g. Apple Pay, Google Pay)
    // No action needed — they can try again
    return;
}

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

// Submit succeeded — continue with confirmPayment()
const result = await rootline.confirmPayment({
    components,
    returnUrl: "https://example.com/payment/complete",
});

if ("error" in result) {
    if (result.error.code === "payment_failed") {
        // Payment was declined — create a new payment and let the customer try again
        document.getElementById("error-message").textContent = result.error.message;
        startNewPayment();
    } else {
        // Something went wrong — show the message, customer can retry
        document.getElementById("error-message").textContent = result.error.message;
    }
}