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

***

## 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;
});
```

***

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

### 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](/sdk/primer-checkout-web/components/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

<CardGroup cols={2}>
  <Card title="Save payment methods" icon="arrow-up-right-from-square" href="https://primer.io/docs/payment-services/save-payment-methods">
    Backend configuration
  </Card>

  <Card title="primer-show-other-payments" icon="cube" href="/sdk/primer-checkout-web/components/primer-show-other-payments">
    Collapse other methods
  </Card>

  <Card title="Events guide" icon="bolt" href="/checkout/primer-checkout/configuration/events">
    Event handling patterns
  </Card>
</CardGroup>