CartThrob 10 documentation for ExpressionEngine commerce teams Visit CartThrob.com
CartThrob.com

Save Vault Checkbox

save_vault_checkbox lets a logged-in customer request that their payment method be saved during checkout. It outputs a checkbox for use inside checkout_form.

With the default form-choice discovery enabled, this tag inside checkout_form opens the signed save-card choice automatically. A fixed force_vault="yes" or force_vault="no" on that form takes precedence; remove the fixed parameter to let the customer choose. The checkbox does not save a card from other CartThrob forms.

Use it on ordinary checkouts. A checkout whose cart contains a subscription item always saves the card, because renewals are charged to it, so the checkbox has no effect there and doesn’t need to be shown. For this reason the CartThrob Subscriptions example save_card_checkout uses a regular store cart; see Understanding the example templates.

See also:

Parameters

id

Optional HTML id for the generated checkbox.

id="save_vault"

checked

Boolean-style initial checked state; default unchecked.

checked="yes"

Output

Outputs an <input type="checkbox"> with:

  • name="VLT"
  • the encrypted y value from save_vault_field_value
  • optional id and checked state

If the member is not logged in, this tag returns no output. Unticking an open choice sends no save-card request and is not an error.

Behavior and Constraints

Inside checkout_form, the generated checkbox opens the choice through discovery. If discovery is disabled, declare options:force_vault="yes|no" on the form instead. A fixed force_vault= still wins over either declaration and checking the box cannot change it.

For a hand-written checkbox, radio group or select with plain values, declare options:force_vault="yes|no" on checkout_form. Name the input force_vault or VLT. The accepted spellings are y, n, yes, no, 1, 0, on, off, true, false, t and f, ignoring case. A bare checkbox posts on and works when the choice is open. A posted value outside the signed set stops checkout with “Choose a valid option.”

Without an opened choice, a posted save-card value is ignored. Template debugging explains a fixed force_vault= or a save-card control used in another form.

Examples

Generated checkbox:

{exp:cartthrob:checkout_form return="store/order_complete"}
    {gateway_fields}
    <label>
        {exp:cartthrob:save_vault_checkbox id="save_vault" checked="no"}
        Save this payment method for future purchases
    </label>
    <button type="submit">Pay</button>
{/exp:cartthrob:checkout_form}

Hand-written checkbox; the explicit list opens the choice:

{exp:cartthrob:checkout_form
    options:force_vault="yes|no"
    return="store/order_complete"}
    {gateway_fields}
    <label><input type="checkbox" name="force_vault" value="yes"> Save my card</label>
    <button type="submit">Pay</button>
{/exp:cartthrob:checkout_form}

Keep the checkout fields and payment JavaScript your gateway requires. To make saving a fixed form decision, set force_vault="yes" or force_vault="no" on checkout_form.