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:
- Validate the form.
- Finalize a server quote (
{checkout_quote_url}). - Confirm with the shopper if the total changed
(
reviewFinalizedQuote/price_change_handling). - Prepare the remote payment from
quote.amount(integer minor units), not from the page-load cart total. - Confirm with the provider, keep
checkout_quote_idon the form, callCartthrobTokenizer.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.