Payments

Overview

A payment gateway is a company that is used as a middleman to capture payments from your customer before being deposited to your bank account. The payments settings is where you will configure your payment gateway and get details about your specific gateway configuration.

Included Gateways

The following payment gateways are included with CartThrob:

Gateway	Description
Authorize.net API	Accepts card payments through Authorize.net Accept.js and supports authorize-only or authorize-and-capture transactions.
Dummy Gateway	Test gateway for development checkout flows without sending transactions to a real processor.
Mollie	Offsite Mollie checkout for hosted payment methods using Mollie API credentials and locale settings.
Offline Payments	Records orders for payments handled outside an online processor, such as phone, invoice, or manual payment workflows.
Opayo Europe Direct	Direct Opayo/Sage Pay card processing using the merchant vendor name and mode settings.
Opayo Europe Offsite (Server)	Redirects customers to Opayo-hosted payment pages and receives payment updates through the offsite callback flow.
PayPal Advanced	PayPal checkout with customizable card fields using PayPal API credentials.
PayPal Standard	PayPal button checkout with optional PayPal Credit, credit card, Venmo, MyBank, Bancontact, and EPS funding sources.
Stripe (Card Element)	Stripe card checkout using Stripe.js / Elements, with authorize/capture, refund, token, and void support.
Stripe (Payment Element)	Stripe Payment Element checkout for cards, Apple Pay, Google Pay, and other enabled Stripe payment methods.

Custom Gateway Development

To build your own payment gateway, start with the Payment Gateway Plugin API in these docs. It covers the current CartThrob 9.x PaymentPlugin API, TransactionState return values, checkout fields, and optional refund/token/offsite interfaces.

CartThrob also maintains a Git repository of sample gateways and a GitHub Wiki with additional examples. Use those as supplements after reading the local API guide.

Paid Gateway Development

Paid gateway development services are available. Please contact us for more details and to confirm pricing and timeline. Before beginning custom development we will need the following:

Developer documentation
Testing credentials for the Payment Gateway

Gateway Configuration

Select a Gateway

There are 2 dropdowns. One is for setting the primary gateway to be used in transactions. If no gateway is specified, this is the gateway that will be used.

The second dropdown is used to select a gateway to configure. You can select multiple gateways and configure them before submitting your changes to be saved.

Gateway Settings

Each gateway has different settings specific to the gateway. These settings are documented individually. The only common setting is the HTML Template. Each gateway can automatically output all of its required HTML in the checkout form. If you would like to override the default HTML and choose your own template, you can set that template here. Beneath the gateway settings, you can find a sample of the HTML that is output in the checkout form to use as a basis for creating your own template.

Gateway field ownership

For a standard checkout, place {gateway_fields} in checkout_form once and let the selected gateway provide its customer and payment fields. Do not add handwritten copies of fields already present in that output; duplicate names or IDs can make validation display against one input while another value is submitted.

A Gateway Fields Template is a full replacement for the default output, not an additional fragment. If you configure one, it must provide every customer field and gateway integration element the checkout requires. Gateways with an Enable Fields setting can omit their standard customer fields; when those fields are disabled, the checkout template must provide any required customer inputs exactly once.

Inline error handling is compatible with generated gateway fields, but the checkout template controls where the errors appear. See Gateway-generated fields and inline errors.

Payment Security Settings

It’s best to allow as little possibility for someone to exploit your system as you can. This section does a few important things.

Validate Credit Card Number

If you are capturing credit card number, CartThrob can do a Luhn Check (Modulus 10 check) on the credit card before sending it on to your gateway. All gateways do this check, as well as additional checks, so this may not be needed.

Allow Gateway Selection in Checkout Form

Gateway selection requires all three of these steps:

Enable and configure each payment gateway.
Set Allow Gateway Selection in Checkout Form to Yes and check each gateway that may be selected.
Add gateway_select, or equivalent gateway controls, to the storefront template.

Enabling a gateway does not automatically display it at checkout. The checked list is an allowlist; the template still owns the customer-facing selector and gateway fields.

Gateways with hosted JavaScript fields, including Stripe and Authorize.net, must not have conflicting scripts and fields mounted together. A full-page reload that saves the selected gateway and then renders only that gateway’s {gateway_fields} is supported and recommended. See Allow the customer to select a gateway.