CartThrob 10 documentation for ExpressionEngine commerce teams Visit CartThrob.com
CartThrob.com

Updating custom checkout JavaScript for CartThrob 10

Released CartThrob docs before CartThrob 10 never shipped a working custom checkout JavaScript sample. custom_js="yes" only said: turn off the gateway’s form_extra and provide your own. In practice that meant copying the bundled Stripe, PayPal, or Authorize.net script from views/payment_gateways/*/form_extra.php.

This page is the pre-10 → 10 translation of that script. The full contract, event payloads, and tokenizer helpers are in Custom checkout JavaScript. Amounts and {checkout_total} are in Checkout Amounts and Payment Review.

If you never set custom_js="yes" and never pasted form_extra into a template, stop here. The upgrade replaces the bundled script for you.

What has to change

Old native JavaScript created the remote payment when the checkout page rendered, from {cart_total}. Submit only confirmed that already-created Stripe PaymentIntent or PayPal order, then posted hidden fields and submitted the HTML form.

On an upgraded store, CartThrob 10 can temporarily accept that legacy POST (payment-intent-id, paypal-order-id, Authorize.net opaque tokens) while cartthrob_legacy_custom_js_checkout remains enabled and when the remote amount still matches the current CartThrob total. It will not authorize a mismatch. If a checkout-page coupon, new shipping address, or price / shipping / tax changed the total after page load, Stripe or PayPal may already have the money and CartThrob will fail the order for merchant review.

Use Version Review to locate affected checkouts. The compatibility setting is an upgrade bridge, not the permanent v10 integration path.

The compatible sequence is:

  1. Validate the form.
  2. Finalize a server quote ({checkout_quote_url}).
  3. Confirm with the shopper if the total changed (reviewFinalizedQuote / price_change_handling).
  4. Prepare the remote payment from quote.amount (integer minor units), not from the page-load cart total.
  5. Confirm with the provider, keep checkout_quote_id on the form, call CartthrobTokenizer.success().

Until that sequence exists, remove checkout price, shipping, tax, allow_user_price, and allow_user_shipping. With custom_js="yes" those parameters error the checkout form at render.

Keep id="checkout_form" (or pass the same id to init()).

Stripe Payments — before and after

This is the 9.0 bundled Stripe Payments form_extra (the script people copied), then the CartThrob 10 replacement. Appearance / Elements mounting is unchanged and omitted.

9.0 (page-load PaymentIntent)

The form_extra PHP created a PaymentIntent while rendering the checkout page and printed clientSecret into the script. Submit only confirmed that intent.

// 9.0: clientSecret already existed from page render.
const elements = stripe.elements({
    clientSecret: clientSecretFromPageLoad,
    appearance: { /* theme, rules, variables, labels */ }
});
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');

CartthrobTokenizer.onSubmit(function () {
    var cardholderName = [
        CartthrobTokenizer.getElementById('first_name'),
        CartthrobTokenizer.getElementById('last_name')
    ].join(' ');

    stripe.confirmPayment({
        elements: elements,
        confirmParams: {
            return_url: returnUrl,
            payment_method_data: {
                billing_details: {
                    email: CartthrobTokenizer.getElementById('email_address'),
                    phone: CartthrobTokenizer.getElementById('phone'),
                    name: cardholderName,
                    address: {
                        city: CartthrobTokenizer.getElementById('city'),
                        line1: CartthrobTokenizer.getElementById('address'),
                        line2: CartthrobTokenizer.getElementById('address2'),
                        state: CartthrobTokenizer.getElementById('state'),
                        postal_code: CartthrobTokenizer.getElementById('zip')
                    }
                }
            }
        },
        redirect: 'if_required'
    }).then(function (result) {
        if (result.error) {
            CartthrobTokenizer.error(result.error.message);
        } else {
            CartthrobTokenizer.addHidden('payment-method-id', result.paymentIntent.payment_method);
            CartthrobTokenizer.addHidden('payment-intent-id', result.paymentIntent.id);
            CartthrobTokenizer.addHidden('client-secret', result.paymentIntent.client_secret);
            CartthrobTokenizer.success();
        }
    });
});

CartThrob 10 (quote, then prepare, then confirm)

{checkout_quote_url} and {checkout_confirm_url} parse only inside {exp:cartthrob:checkout_form}. Put them on a data attribute in the tag pair. The prepare URL is the Stripe action prepare_stripe_payments_checkout_action from the current bundled form_extra.php — not a template path.

{exp:cartthrob:checkout_form
    id="checkout_form"
    custom_js="yes"
    error_handling="inline"
    price_change_handling="review"
    return="order/complete"
}
    <p>Total: {checkout_total}</p>
    <div id="payment-element"></div>
    <div
        id="ct-checkout-actions"
        data-quote-url="{checkout_quote_url}"
        data-confirm-url="{checkout_confirm_url}"
    ></div>
    <button type="submit">Place order</button>
{/exp:cartthrob:checkout_form}

<script src="{theme_folder_url}user/cartthrob/scripts/cartthrob-tokenizer.js"></script>
// CartThrob 10: do not create a PaymentIntent until the quote exists.
var actions = document.getElementById('ct-checkout-actions');
var quoteUrl = actions.getAttribute('data-quote-url');
var confirmUrl = actions.getAttribute('data-confirm-url');
var prepareUrl = '...'; // prepare_stripe_payments_checkout_action

var elements = stripe.elements({
    mode: 'payment',
    amount: pageLoadAmountMinorUnits,
    currency: storeCurrency,
    captureMethod: 'manual',
    paymentMethodTypes: ['card'],
    appearance: { /* same as before */ }
});
var paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');

CartthrobTokenizer.init('checkout_form');

function finalizeQuote() {
    return CartthrobTokenizer.postCheckout(quoteUrl).then(function (data) {
        if (!data.quote || !data.quote.id) {
            throw new Error('CartThrob checkout details are unavailable.');
        }

        CartthrobTokenizer.setHidden('checkout_quote_id', data.quote.id);

        return CartthrobTokenizer.reviewFinalizedQuote(data, confirmUrl);
    }).then(function (quote) {
        CartthrobTokenizer.setHidden('checkout_quote_id', quote.id);
        return quote;
    });
}

CartthrobTokenizer.onSubmit(function () {
    finalizeQuote().then(function (quote) {
        if (quote.amount === 0) {
            CartthrobTokenizer.success();
            return;
        }

        elements.update({ amount: quote.amount });

        return elements.submit().then(function (submission) {
            if (submission.error) {
                throw submission.error;
            }

            return CartthrobTokenizer.postCheckout(prepareUrl);
        }).then(function (data) {
            if (!data.quote || data.quote.id !== quote.id
                || !data.client_secret
            ) {
                throw new Error('Stripe payment details are unavailable.');
            }

            return stripe.confirmPayment({
                elements: elements,
                clientSecret: data.client_secret,
                confirmParams: {
                    return_url: returnUrl,
                    payment_method_data: {
                        billing_details: { /* same fields as 9.0 */ }
                    }
                },
                redirect: 'if_required'
            });
        }).then(function (result) {
            if (result.error) {
                throw result.error;
            }

            if (result.paymentIntent) {
                CartthrobTokenizer.setHidden(
                    'payment-method-id',
                    result.paymentIntent.payment_method
                );
                CartthrobTokenizer.setHidden(
                    'payment-intent-id',
                    result.paymentIntent.id
                );
                CartthrobTokenizer.setHidden(
                    'client-secret',
                    result.paymentIntent.client_secret
                );
            }

            CartthrobTokenizer.success();
        });
    }).catch(function (error) {
        if (CartthrobTokenizer.handleCheckoutError(error)) {
            return;
        }
        if (CartthrobTokenizer.handleCheckoutCancellation(error)) {
            return;
        }
        CartthrobTokenizer.error(error.message || 'Payment could not be confirmed.');
    });
});

Stripe checklist

Before CartThrob 10 CartThrob 10
PaymentIntent created while the page rendered Elements start in mode: 'payment' with a placeholder amount. No PaymentIntent yet.
confirmPayment used the page-load clientSecret Finalize the quote, elements.update({amount: quote.amount}), POST prepare, then confirmPayment with that client_secret.
Hidden fields: payment-intent-id, client-secret, payment-method-id Same three fields, plus checkout_quote_id from the quote.
addHidden Prefer setHidden so a retry does not stack duplicate inputs.
form.submit() via Tokenizer.success() Still success(). Do not call form.submit() yourself while the tokenizer listener is attached.
Errors only from Stripe Call handleCheckoutError then handleCheckoutCancellation before treating a failure as a declined card.
Charged {cart_total} from render Charge quote.amount (minor units). Show {checkout_total} to the shopper.

Copy the current bundled views/payment_gateways/stripe_payments/form_extra.php if you want the production version of this path rather than maintaining your own.

PayPal Advanced and PayPal Standard

Same shape as old Stripe. Earlier versions created the PayPal order on page render (orderId / Buttons) and submit only posted paypal-order-id or ref-id.

CartThrob 10: finalize the quote first, then POST prepare_paypal_advanced_checkout_action or prepare_paypal_standard_checkout_action (from that gateway’s current form_extra.php). Hosted Fields / Buttons must use the order id returned after the quote, not the id printed at page load. Keep checkout_quote_id on the form through capture.

If you leave the old script in place, a total that changed after page load can capture at PayPal and fail the CartThrob order.

Authorize.net

Old Authorize.net JavaScript only tokenized the card on submit (opaqueDataDescriptor / opaqueDataValue). The charge used CartThrob’s total at charge time, so a straight copy often still works when the form has no checkout override parameters.

Still add the quote step if you use price, shipping, tax, or any other checkout-level amount control, or if you want the same mismatch protection as Stripe. Built-in CartThrob 10 Authorize.net JavaScript tokenizes after the quote is confirmed. Do not create an Authorize.net transaction from a page-load amount.

If you do not update the script

Situation CartThrob 10 result
Copied pre-10 Stripe/PayPal JS, no overrides, no checkout-page coupon, tax/shipping did not change The temporary upgrade bridge can authorize while it remains enabled.
Same script, then the total changes before submit Remote payment can succeed; CartThrob order fails (ct.payments.amount_currency_mismatch). Refund or capture in the provider dashboard.
custom_js="yes" plus price / tax / shipping / allow_user_* Checkout form does not render (unsupported-overrides error).
Stripe or PayPal subscription checkout with those params Same render error. Subscriptions do not have built-in quotes yet — remove the params.
Custom form id while the new tokenizer still looks up checkout_form Console error and a one-time alert. Pass your id into init().

There is no setting to turn the amount check off. Applying coupons and destination before payment, and dropping override params until the quote path exists, is the safe holding pattern.

See also