> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```javascript theme={"dark"}
const checkout = document.querySelector('primer-checkout');
checkout.options = {
  vault: { enabled: true }
};
```

### Custom Layout

Include manually when using custom layouts:

```html theme={"dark"}
<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

```html theme={"dark"}
<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

```javascript theme={"dark"}
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

```javascript theme={"dark"}
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](https://primer.io/docs/payment-services/save-payment-methods.md).

***

## 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

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

### Selecting a Saved Payment Method on Load

By default, no saved payment method is selected when the vault loads. To select one programmatically, call `primer.vault.select()` once the methods are loaded. The selection behaves like a customer click: it fires `primer:vault-selection-change`, and shows the CVV input when CVV recapture is required.

```javascript theme={"dark"}
let primer;
checkout.addEventListener('primer:ready', (event) => {
  primer = event.detail;
});

checkout.addEventListener('primer:vault-methods-update', (event) => {
  const { vaultedPayments } = event.detail;
  // getPreferredMethodId is your own logic, not part of the SDK.
  // Return the id of the method to select, e.g. the last used card.
  const methodId = getPreferredMethodId(vaultedPayments);
  if (methodId) primer.vault.select(methodId);
});
```

Choosing which method to select is up to you. To select the customer's default method, call [List saved payment methods](https://primer.io/docs/api-reference/v2.4/api-reference/payment-methods-api/list-saved-payment-methods.md) from your server and pass the `token` of the method marked `default: true` to `primer.vault.select()`. The `token` is the same value as the `id` in `primer:vault-methods-update`.

> [!NOTE]
>
> Available from v1.11.0.

***

## 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:

```javascript theme={"dark"}
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 |
| `primer.vault.select(id)` | Select a vaulted method (or clear with `null`) |

### 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](https://primer.io/docs/sdk/primer-checkout-web/components/primer-show-other-payments.md) | 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

> [card] [Save payment methods](https://primer.io/docs/payment-services/save-payment-methods.md)
>
> Backend configuration

> [card] [primer-show-other-payments](https://primer.io/docs/sdk/primer-checkout-web/components/primer-show-other-payments.md)
>
> Collapse other methods

> [card] [Events guide](https://primer.io/docs/checkout/primer-checkout/configuration/events.md)
>
> Event handling patterns


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.