Vault Manager Component

Displays and manages saved payment methods for returning customers.

<primer-vault-manager>

Displays saved payment methods for returning customers. Supports viewing, selecting, deleting, and paying with vaulted methods. Includes CVV recapture when required.

Quick Reference

Parent	<primer-checkout>
Requires	options.vault.enabled: true
Slot	submit-button
Emits	primer:vault-methods-update, primer:vault-selection-change
Listens for	primer:vault-submit

---

Examples

Basic (auto-integrated)

When vault is enabled, appears automatically in the default layout:

const checkout = document.querySelector('primer-checkout');
checkout.options = {
  vault: { enabled: true }
};

Custom Layout

Include manually when using custom layouts:

<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="payments">
      <primer-vault-manager></primer-vault-manager>
      
      <primer-show-other-payments>
        <div slot="other-payments">
          <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
        </div>
      </primer-show-other-payments>
    </div>
  </primer-main>
</primer-checkout>

Custom Submit Button

<primer-vault-manager>
  <button slot="submit-button" type="submit">Pay with Saved Card</button>
</primer-vault-manager>

Button requirements: type="submit" or data-submit attribute.

External Submit Button

document.getElementById('my-pay-button').addEventListener('click', () => {
  document.dispatchEvent(
    new CustomEvent('primer:vault-submit', {
      bubbles: true,
      composed: true
    })
  );
});

Note: bubbles: true and composed: true are required for shadow DOM traversal.

---

Configuration

checkout.options = {
  vault: {
    enabled: true,       // Required
    headless: false,     // Hide default UI for custom implementation
    showEmptyState: true
  }
};

Backend required: Your client session must be configured for vaulting. See Save Payment Methods.

---

Events

Emitted Events

Event	When	Payload
primer:vault-methods-update	Methods loaded/changed	{ vaultedPayments, cvvRecapture }
primer:vault-selection-change	User selects method	{ paymentMethodId, timestamp }

Listened Events

Event	Purpose
primer:vault-submit	Triggers payment with selected method

Tracking Selection

checkout.addEventListener('primer:vault-selection-change', (event) => {
  const { paymentMethodId } = event.detail;
  submitButton.disabled = !paymentMethodId;
});

---

Slots

Slot	Description	Requirements
submit-button	Custom submit button	type="submit" or data-submit

---

States

State	Description
Loading	Fetching saved methods
Empty	No saved methods
List	Showing methods with submit button
Edit	Managing methods (delete)
Delete Confirmation	Confirming deletion
Processing	Payment in progress

---

Headless Mode

Build completely custom vault UI while retaining full functionality:

checkout.options = {
  vault: {
    enabled: true,
    headless: true
  }
};

checkout.addEventListener('primer:ready', (event) => {
  const primer = event.detail;
  
  primer.onVaultedMethodsUpdate = async ({ vaultedPayments, cvvRecapture }) => {
    const methods = vaultedPayments.toArray();
    
    methods.forEach(method => {
      if (method.paymentInstrumentType === 'PAYMENT_CARD') {
        const { network, last4Digits } = method.paymentInstrumentData;
        // Render: Visa •••• 4242
      }
    });
    
    if (cvvRecapture) {
      const cvvInput = await primer.vault.createCvvInput({
        cardNetwork: methods[0].paymentInstrumentData.network,
        container: '#cvv-container'
      });
    }
  };
});

Headless Methods

Method	Description
primer.vault.createCvvInput(options)	Create CVV input for recapture
primer.vault.startPayment(id, options?)	Start payment with vaulted method
primer.vault.delete(id)	Delete a vaulted method

Payment Data by Type

Type	Fields
PAYMENT_CARD	network, last4Digits, cardholderName, expirationMonth, expirationYear
PAYPAL_BILLING_AGREEMENT	email, firstName, lastName, externalPayerId
KLARNA_CUSTOMER_TOKEN	email, firstName, lastName
ACH	accountNumberLastFourDigits, bankName, accountType

---

CSS Properties

Layout

Property	Description	Default
--primer-space-small	Gap between saved payment methods	8px
--primer-space-medium	Internal padding	12px
--primer-space-xlarge	Section spacing	20px

Typography

Property	Description	Default
--primer-typography-title-large-size	Header text size	16px
--primer-typography-title-large-weight	Header text weight	550
--primer-typography-body-medium-size	Card details text	14px
--primer-typography-body-small-size	Secondary info text	12px

Colors

Property	Description
--primer-color-text-primary	Primary text color
--primer-color-text-secondary	Secondary text (card details)
--primer-color-text-disabled	Disabled text
--primer-color-icon-primary	Payment method icons

Borders & Backgrounds

Property	Description
--primer-color-border-outlined-default	Card item border
--primer-color-border-outlined-selected	Selected card border
--primer-color-background-outlined-default	Card item background
--primer-color-background-outlined-hover	Hover background
--primer-radius-medium	Card item border radius

Delete Confirmation

Property	Description
--primer-color-red-100	Warning background
--primer-color-red-500	Delete button color
--primer-color-text-negative	Warning text

Animation

Property	Description	Default
--primer-animation-duration	Transition duration	200ms
--primer-animation-easing	Transition easing	cubic-bezier(0.44, 0, 0.4, 1)

---

Dependencies

Works with:

Component	Purpose
primer-show-other-payments	Collapses other methods when vault has saved cards

---

Usage Guidelines

Do

• Enable vault in SDK options: vault: { enabled: true }
• Configure client session on backend for vaulting
• Use with <primer-show-other-payments> in custom layouts
• Track selection state for custom submit buttons

Don’t

• Don’t use without backend vault configuration
• Don’t mix default UI with headless mode
• Don’t forget to handle empty state UX

---

Content Guidelines

Delete confirmation

Do	Don’t
”Remove this card?"	"Delete?"
"Visa ending in 4242 will be removed"	"Are you sure?”

Empty state

Do	Don’t
”No saved payment methods"	"Empty"
"Save a card for faster checkout next time"	"Nothing here”

---

See also

Save payment methods

Backend configuration

primer-show-other-payments

Collapse other methods

Events guide

Event handling patterns