Gateway Select

gateway_select outputs an HTML <select> of checkout gateways available to the current cart/session context.

This is commonly used on checkout pages with checkout_form so customers can switch payment method.

See also:

• checkout_form
• gateway_fields
• selected_gateway_fields
• gateway_fields_url

Parameters

• name
• selected
• add_blank
• gateways
• encrypt
• extra
• onchange
• class
• id

name

Input name for the <select>. Defaults to gateway.

name="gateway"

selected

Selected gateway value.

• Typically this is a gateway class short name (for example Cartthrob_stripe or current {gateway} value from customer info).
• If the value is encoded, the tag will decode and resolve it when possible.

• If selected value is not valid for current available gateways, selection falls back to the configured default gateway.

  selected=”{gateway}”

add_blank

Adds a blank --- option at the top.

add_blank="yes"

gateways

Restricts the dropdown to specific gateways using a pipe-delimited list of gateway short names.

gateways="stripe|mollie"

Notes:

• Values are matched against configured selectable gateways.
• If gateway selection is disabled in settings, this restriction is ignored and only default gateway is shown.

encrypt

Controls whether option values are encrypted.

• Default behavior: encrypted values (encrypt="yes" / omitted).

• Set encrypt="no" for plain class-name values.

  encrypt=”no”

extra

Additional raw attributes appended to the <select>.

extra='data-role="gateway-select" aria-label="Payment Gateway"'

id

id attribute for the <select>.

id="gateway"

class

class attribute for the <select>.

class="checkout-gateway-select"

onchange

Inline JavaScript onchange attribute for the <select>.

onchange="refreshGatewayFields(this.value)"

Output

Returns an HTML <select> element with gateway options.

• Option labels are gateway titles (localized where available).
• Options are sorted alphabetically by label before rendering.

Behavior and Constraints

1. If allow_gateway_selection is disabled, output is forced to a single default gateway option.
2. If cart contains subscription items, gateway options are filtered to subscription-capable gateways only.
3. Option values are encrypted by default.
4. If gateways is provided, list is intersected with configured available gateways.
5. selected value is normalized against available options; invalid values fall back to default gateway.
6. Attributes from id, class, onchange, and extra are merged onto the <select>.

Examples

Basic checkout usage:

{exp:cartthrob:gateway_select id="gateway"}

Keep selection in sync with saved customer gateway:

{exp:cartthrob:customer_info}
    {exp:cartthrob:gateway_select id="gateway" selected="{gateway}"}
{/exp:cartthrob:customer_info}

Restrict selectable gateways and include a blank option:

{exp:cartthrob:gateway_select
    id="gateway"
    gateways="stripe|mollie"
    add_blank="yes"
}

Plain (non-encrypted) option values for custom integrations:

{exp:cartthrob:gateway_select
    id="gateway"
    encrypt="no"
    onchange="refreshGatewayFields(this.value)"
}