Add Vault Form (tag pair)

{exp:cartthrob:add_vault_form} outputs an HTML form that creates a saved payment method (vault token) for the current member.

This is a form tag (tag pair), and it is commonly used in checkout-related account flows.

See also:

• update_vault_form
• delete_vault_form
• checkout_form
• gateway_fields
• selected_gateway_fields
• gateway_fields_url
• global_form_settings

Parameters

In addition to the tag-specific parameters below, this tag supports shared form parameters from global_form_settings (for example error_handling, show_errors, id, class, name, onsubmit, enctype, action, and validation rules).

return

Return path used after action completion.

return="store/vaults/created"

secure_return

If truthy, return URLs are forced to HTTPS.

secure_return="yes"

language

Optional language value passed into action processing.

language="english"

logged_out_redirect

Used by logged-out guard behavior for this form.

logged_out_redirect="account/login"

gateway

Requested payment gateway short name.

Notes:

• This is only honored when allow_gateway_selection is enabled in CartThrob settings.

• If omitted, CartThrob can fall back to the gateway stored in cart customer info.

  gateway=”stripe”

gateway_method

Optional gateway method value (gateway-specific).

gateway_method="ideal"

required

Pipe-delimited required fields for this form.

required="first_name|name"

required="not ..." is also supported and is converted internally to a not_required list that excludes fields from required gateway-field validation:

required="not first_name|last_name"

authorized_redirect

Optional success-status redirect.

authorized_redirect="store/vaults/authorized"

failed_redirect

Optional failed-status redirect.

failed_redirect="store/vaults/failed"

declined_redirect

Optional declined-status redirect.

declined_redirect="store/vaults/declined"

processing_redirect

Optional processing-status redirect.

processing_redirect="store/vaults/processing"

member_id

Passed through as form data. Use only where your flow intentionally submits on behalf of a specific member context.

member_id="123"

name

Optional tag parameter to pre-set submitted vault name value.

name="My Primary Card"

custom_js

When truthy, disables automatic gateway JS/markup extras appended by gateway integrations (vault_form_extra() or form_extra()).

custom_js="yes"

Variables

This form includes global tag/form variables, plus add-vault specific values.

{vault_fields}

If {vault_fields} is present in tag body content, CartThrob replaces it with gateway-generated vault fields HTML (gateway_fields(..., 'vault_fields')).

{name}

Repopulated from posted name value after submission attempts.

{primary}

Repopulated from posted primary value after submission attempts.

Inline error variables

When inline error handling is used, form error variables are available (for example errors_exist, {errors}, error:field_name).

Form Fields

Common fields used in templates:

• name
• primary
• Gateway-specific fields rendered via {vault_fields}

Customer/billing/shipping fields can also be included and are processed through checkout customer-info flow during add-vault submission.

Behavior and Constraints

1. This tag enforces logged-out guard behavior.
2. If no id parameter is provided, it defaults to checkout_form.
3. Gateway resolution order is:
   1. explicit gateway parameter (if gateway selection is allowed),
   2. existing cart customer gateway value.
4. required="not ..." is converted to an exclusion list for gateway-required field validation.
5. Unless custom_js is enabled, gateway-specific extra markup/scripts may be appended.
6. Submit action flow (add_vault_action) validates required fields, creates a vault token via vault service, and completes through form-builder callbacks/redirect rules.

Examples

Basic create-vault form:

{exp:cartthrob:add_vault_form
  error_handling="inline"
  class="form-horizontal"
  required="first_name|name"
  return="store/vaults/created"}
  <input type="text" name="name" value="{name}" />
  <input type="checkbox" name="primary" value="1" {if primary == 1}checked="checked"{/if} />

  {vault_fields}

  <input type="submit" value="Create Payment Method" />
{/exp:cartthrob:add_vault_form}

Exclude specific gateway-required fields:

{exp:cartthrob:add_vault_form
  required="not first_name|last_name"
  return="store/vaults/created"}
  {vault_fields}
  <input type="submit" value="Save" />
{/exp:cartthrob:add_vault_form}

No explicit return path:

{exp:cartthrob:add_vault_form}
  {vault_fields}
  <input type="submit" value="Save" />
{/exp:cartthrob:add_vault_form}