Stripe Payment Gateway
The Stripe Payment Gateway will allow your CartThrob site to accept payments through the Stripe Payments platform. Stripe allows for secure credit card processing using their robust REST APIs so no sensitive details ever touch your systems.
Note that the Stripe Payment Gateway has 2 options for integration with both allowing for different UI/X options and configurations. Be sure to review your requirements select which option fits your needs best.
Payment Element
The Stripe Payment Element gateway allows customers to use a Credit Card, Google Pay, Apple Pay, and many other third party options, all configurable within your Stripe Dashboard.
Checkout and PaymentIntent Sequence
The built-in non-subscription Stripe Payments flow separates CartThrob checkout validation from remote payment preparation:
- validate supported CartThrob checkout fields;
- let Stripe Elements validate payment fields;
- finalize the server-authoritative checkout quote;
- pause for customer confirmation if the amount changed;
- prepare a PaymentIntent for the confirmed quote;
- confirm the Stripe payment method;
- complete CartThrob checkout against the same quote and payment.
This ordering reduces abandoned PaymentIntents when ordinary form or Stripe field validation fails.
A prepared PaymentIntent can still be canceled when checkout safely rejects or supersedes it after preparation. In Stripe:
- no PaymentIntent generally means failure occurred before preparation;
- a canceled PaymentIntent can represent cleanup for an unfinished checkout and is not a completed charge;
- a succeeded or captured PaymentIntent should match the saved CartThrob order total, currency, transaction ID, and order reference.
Cancellation depends on the remote PaymentIntent status; CartThrob cannot cancel an intent after Stripe no longer permits it.
Checkout Form Requirements
When using built-in gateway JavaScript, omit the checkout-form id or
use id="checkout_form". CartThrob supplies this ID by default. Use a
CSS class for styling rather than replacing the functional ID.
Built-in finalized-quote support applies to non-subscription Stripe Payments. Custom JavaScript and subscription checkout must implement their own correct validation, quote, confirmation, preparation, and completion sequence before using amount-changing checkout controls. See Custom checkout JavaScript.
Stripe amounts use the currency’s minor-unit precision. Do not assume that every currency has two decimal places or derive the remote amount from display formatting alone.
Card Element
If all you need is a vanilla credit card input form then the Card Element may be all you need. Simple. Consistent. Easily configurable. No fuss, no muss.
Adding Meta Data to an Order
You can include data about on Order within your Stripe Dashboard by adding a hidden form field within your cartthrob:checkout_form tags for each meta data value you want to send.
See the Stripe API docs for complete details.
You’ll need to make sure your form names are prefixed with meta: and then the key for your data point. For example, <input type="hidden" name="meta:my_key_name" value="Special data I want stored on Stripe" />
Stripe’s requirements for metadata are:
- Up to 20 keys
- Key names up to 40 characters
- Values up to 500 characters
Example
{exp:cartthrob:checkout_form
error_handling="inline"
class="form-horizontal"
required="first_name";
return="{template_group}/order_info"}
<div id="checkout_form_gateway_fields">
{gateway_fields}
</div>
<input type="hidden" name="meta:test_key" value="Some value goes here" />
<input type="hidden" name="meta:test_key2" value="A different value goes here" />
{/exp:cartthrob:checkout_form}