Skip to main content

Saved Payment Methods

Save a Payment Method​

To save a payment method, use the method.register() method. It takes an optional name parameter to assign a name to the token.


<div id="root">
    <div id="form"></div>
    <label for="save-token">Save this payment method
        <input type="checkbox" id="save-token"/>
    </label>
    <label for="name">Name
        <input type="text" id="name"/>
    </label>
    <button id="pay-button" disabled>Pay</button>
</div>
const method = checkout.paymentMethods.value.find((method) => method.method === "creditcard");
const saveTokenCheckbox = document.getElementById("save-token");
const nameInput = document.getElementById("name");

saveTokenCheckbox.addEventListener('change', (e) => {
    if (e.target.checked) {
        const name = nameInput.value || "My Card";
        method.register(true, {name});
    } else {
        method.register(false);
    }
});

You can subscribe to the registration state using the method.registration reactive variable.

method.registration.subscribe((registration) => {
    if (registration.registered) {
        console.log(`Payment method will be registered with name ${registration.name}`);
    } else {
        console.log("Payment method will not be registered");
    }
});

Display Saved Payment Methods​

Users can select a saved payment method using the checkout.paymentTokens reactive variable. Some tokens may require CVV entry, which is handled by the PaymentElement.


<div id="root">
    <div id="form"></div>
    <div id="tokens"></div>
    <button id="pay-button" disabled>Pay</button>
</div>
function displayTokens(tokens) {
    const ul = document.createElement("ul");
    tokens.forEach((token) => {
        const li = document.createElement("li");
        li.textContent = `${token.partner} ${token.method}`;
        li.addEventListener("click", () => {
            const tokenForm = document.getElementById("form");
            tokenForm.innerHTML = "";
            
            // Check if token is disabled before rendering
            if (token.disabled.value) {
                tokenForm.innerHTML = `<p>This payment method is currently unavailable.</p>`;
                return;
            }
            
            const cvvInput = token.getPaymentElement();
            try {
                cvvInput.appendTo(tokenForm);
            } catch (error) {
                if (error.code === 'METHOD_DISABLED') {
                    tokenForm.innerHTML = `<p>This payment method is currently unavailable.</p>`;
                } else {
                    console.error('Failed to render CVV input:', error);
                }
            }
        });
        ul.appendChild(li);
    });
    document.getElementById("tokens").appendChild(ul);
}

checkout.paymentTokens.subscribe(displayTokens);

Sort Tokens by Creation Date​

Each token exposes an optional createdAt field — an ISO 8601 date string. Use it to sort saved payment methods chronologically, for example to display the most recently added first.

const sorted = [...checkout.paymentTokens.value].sort((a, b) => {
    if (!a.createdAt) return 1;
    if (!b.createdAt) return -1;
    return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
});

How to Use a Saved Token​

When a user selects a saved payment method, follow these steps:

  1. Render the Payment Element: Call token.getPaymentElement() to get a payment element (typically for CVV entry if required). Append it to the form.
  2. User Fills CVV: The user enters their CVV in the rendered payment element.
  3. Automatic Primary Source: Once the CVV is validated, the token is automatically set as the primary payment source using token.setAsPrimarySource() in the background.

Select a Token​

Depending on your payment provider, you may need to display a CVV input field for the user to enter their CVV. This is handled by the PaymentElement.

// Let's get the first token in the list
const token = checkout.paymentTokens.value[0];
const cvvInput = token.getPaymentElement({
    hostedForm:  {
        cvvPlaceholder: '123',
        cvv4Placeholder: '1234',
        cvvInputLabel: 'Security code',
        cvv4InputLabel: 'Security code',
        cvvRequiredError: 'Enter your card security code.',
        cvvFormatError: 'Enter a valid security code.',
        cvvCannotBeEmptyError: 'Security code cannot be empty.',
        cvvTooltipText: 'The 3–4 digit code on the back (or front for Amex).'
    }
});
cvvInput.appendTo(document.getElementById("form"));

Hide the CVV Input​

To hide the CVV input, use paymentElement.remove(). This will also deselect the token as described below.

Automatic Cleanup

Calling remove() on a payment element automatically clears the primary payment split.

Deselect a Token​

When a user fill the CVV, the token is automatically set as the primary payment source. To deselect a saved token, use checkout.clearFromPrimarySplit().

Favorite Tokens​

Each primary token exposes an isFavorite reactive store and a setAsFavorite() method. Use these to highlight the user's preferred payment method and pre-select it on load.

// React to favorite state changes
token.isFavorite.subscribe((isFav) => {
    starButton.classList.toggle("active", isFav);
});

To mark a token as the user's favorite:

await token.setAsFavorite();
Wallet session required

setAsFavorite() requires a WalletSession. It throws MISSING_WALLET_SESSION if no wallet session is loaded.

Edit a Token​

Users can rename a saved token using token.edit(). This requires a WalletSession.

const token = checkout.paymentTokens.value[0];

if (!token.name) {
    token.edit({name: "My Card"});
}

Delete a Token​

To remove a saved token, use token.delete(). This requires a WalletSession.

const token = checkout.paymentTokens.value[0];
token.delete();
Refresh Required

Refresh the PaymentSession after editing or deleting a token to reflect changes.

Complete examples​

Save a card during payment​

Loading demo…

Pay with a saved card​

Loading demo…