Tutorials

Enable Payment Services vaulted cards in checkout

15 minutes

This tutorial shows how to let shoppers vault a card during checkout and pay with it during a later purchase. Reusing a saved card requires modifying your commerce-checkout block.

What you’ll build

By the end of this tutorial, you’ll have updated the commerce-checkout block so that shoppers can check out using a card they’ve already saved.

Pay with vaulted card

Selecting a saved card during checkout

Pay with fresh card

Saving a new card during checkout

Prerequisites

Before you begin, make sure you have:

A working Commerce storefront on Edge Delivery Services
Familiarity with customizing blocks in your code repository
Completed the onboarding steps described in Payment Services installation
@dropins/storefront-checkout at version 3.3.2-alpha-20260818085815 in package.json
@dropins/storefront-payment-services at version 4.3.0-beta2 in package.json

Step-by-step

The following steps describe how to update the commerce-checkout block so shoppers can pay with a vaulted card.

Render vaulted card options

This step adds a StoredMethods slot to renderPaymentMethods, rendering each saved card as its own selectable option.

Navigate to the blocks/commerce-checkout/containers.js file and import the VaultedCreditCard container from the Payment Services drop-in.
```
1
import VaultedCreditCard from '/@dropins/storefront-payment-services/containers/VaultedCreditCard.js';
```

In the same file, find the PaymentMethods container rendered in the renderPaymentMethods function.

1
CheckoutProvider.render(PaymentMethods, {
2
  slots: {
3
    Methods: {
4
      // ...your existing entries
5
    },
6
  },
7
})

Add a StoredMethods slot as a sibling of Methods, which renders each saved card.

1
CheckoutProvider.render(PaymentMethods, {
2
  slots: {
3
    Methods: {
4
      // ...your existing entries
5
    },
6
    StoredMethods: {
7
      [PaymentMethodCode.VAULT]: {
8
        tokenCode: PaymentMethodCode.CREDIT_CARD,
9
        render: (ctx) => {
10
          const $storedOption = document.createElement('div');
11

12
          PaymentServices.render(VaultedCreditCard, {
13
            tokenDetails: ctx.details,
14
          })($storedOption);
15

16
          ctx.replaceHTML($storedOption);
17
        },
18
      },
19
    },
20
  },
21
})

Remove the following entry from Methods, if you have one. StoredMethods already excludes registered codes from the live method list, making the explicit enabled: false now redundant.
```
1
[PaymentMethodCode.VAULT]: {
2
  enabled: false,
3
},
```

Place order with vaulted card

This step updates handlePlaceOrder so an order can actually be placed with a vaulted card.

Navigate to the blocks/commerce-checkout/commerce-checkout.js file and find the handlePlaceOrder function.

1
const handlePlaceOrder = async ({ cartId, code }) => {
2
  await displayOverlaySpinner(loaderRef, $loader, $loaderStatus);
3
  try {
4
    // Payment Services credit card
5
    if (code === paymentsApi.PaymentMethodCode.CREDIT_CARD) {
6
      const success = await trySubmitPaymentServicesCreditCard();
7
      if (!success) {
8
        return;
9
      }
10
    }
11
    await orderApi.placeOrder(cartId);
12
  } catch (error) {
13
    console.error(error);
14
    throw error;
15
  } finally {
16
    removeOverlaySpinner(loaderRef, $loader, $loaderStatus);
17
  }
18
};

Extend the if condition that guards the call to trySubmitPaymentServicesCreditCard() so it also matches vaulted cards.

1
const handlePlaceOrder = async ({ cartId, code }) => {
2
  await displayOverlaySpinner(loaderRef, $loader, $loaderStatus);
3
  try {
4
    // Payment Services credit card
5
    if (code === paymentsApi.PaymentMethodCode.CREDIT_CARD
6
      || code === paymentsApi.PaymentMethodCode.VAULT) {
7
      const success = await trySubmitPaymentServicesCreditCard();
8
      if (!success) {
9
        return;
10
      }
11
    }
12
    await orderApi.placeOrder(cartId);
13
  } catch (error) {
14
    console.error(error);
15
    throw error;
16
  } finally {
17
    removeOverlaySpinner(loaderRef, $loader, $loaderStatus);
18
  }
19
};

Adjust billing address options

The boilerplate’s default checkout layout locates the “Bill to shipping” checkbox above the payment options and the billing address form below them. Since a stored card’s billing address is fixed to the card and already rendered inline with it, the checkbox and the form need to be hidden while one is selected. Also, the checkbox needs to move below the payment options, so shoppers are guaranteed to see it on their way to “Place order” if they switch to a method with customizable billing.

To make these changes, adapt your blocks/commerce-checkout block as follows:

Navigate to the blocks/commerce-checkout/commerce-checkout.js file and locate the handleCheckoutValues function.

1
function handleCheckoutValues(payload) {
2
  const { isBillToShipping } = payload;
3
  $billingForm.style.display = isBillToShipping ? 'none' : 'block';
4
}

Replace it with the following code to dynamically hide the billing checkbox and form while a stored card is selected.

1
function handleCheckoutValues(payload) {
2
  const { isBillToShipping, selectedPaymentMethod } = payload;
3
  const isStoredPaymentMethodSelected = !!selectedPaymentMethod?.additionalData?.publicHash;
4

5
  $billToShipping.style.display = isStoredPaymentMethodSelected ? 'none' : 'block';
6
  $billingForm.style.display = (isBillToShipping || isStoredPaymentMethodSelected) ? 'none' : 'block';
7
}

In blocks/commerce-checkout/fragments.js, find the createCheckoutFragment function and ensure both checkout__bill-to-shipping and checkout__billing-form render after checkout__payment-methods, adjusting your layout if needed. In the default layout, only the checkbox needs to move.

Left in its default position above payment options, the checkbox could reappear out of view if a shopper switches from a stored card to a fresh card. By then they’ve already scrolled down to payment options and may never scroll back up to see it. Moving it below payment guarantees it spawns in their path to “Place order” instead.
```
1
<div class="checkout__main">
2
  
3
  <div class="checkout__payment-methods ${CHECKOUT_BLOCK}"></div>
4
  <div class="checkout__bill-to-shipping ${CHECKOUT_BLOCK}"></div>
5
  <div class="checkout__billing-form ${CHECKOUT_BLOCK}"></div>
6
  <div class="checkout__terms-and-conditions ${CHECKOUT_BLOCK}"></div>
7
  <div class="checkout__place-order ${CHECKOUT_BLOCK}"></div>
8
</div>
```
Finally, add the following style rule to blocks/commerce-checkout/commerce-checkout.css to hide the horizontal divisor when the shopper has stored cards.

When a shopper has stored cards, they render inside their own bordered box, so the section’s own divisor becomes a redundant second horizontal line right below it.
```
1
/* No billing section divisor needed when payment methods shown inside separate box */
2
.checkout__payment-methods:has(.checkout-payment-methods__stored-methods) {
3
  padding-bottom: 0;
4
  border-bottom: none;
5
}
```

Example

See blocks/commerce-checkout in the payment-services branch of the boilerplate repository for a reference implementation of the vaulted cards integration. This branch also includes the PayPal, Apple Pay, and Google Pay integration covered in a separate tutorial.