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.
<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: trueSlot submit-buttonEmits primer:vault-methods-update, primer:vault-selection-changeListens 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 >
< 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.
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-updateMethods loaded/changed { vaultedPayments, cvvRecapture }primer:vault-selection-changeUser selects method { paymentMethodId, timestamp }
Listened Events
Event Purpose primer:vault-submitTriggers 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-buttonCustom 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, expirationYearPAYPAL_BILLING_AGREEMENT email, firstName, lastName, externalPayerIdKLARNA_CUSTOMER_TOKEN email, firstName, lastNameACH accountNumberLastFourDigits, bankName, accountType
CSS Properties
Layout
Property Description Default --primer-space-smallGap between saved payment methods 8px--primer-space-mediumInternal padding 12px--primer-space-xlargeSection spacing 20px
Typography
Property Description Default --primer-typography-title-large-sizeHeader text size 16px--primer-typography-title-large-weightHeader text weight 550--primer-typography-body-medium-sizeCard details text 14px--primer-typography-body-small-sizeSecondary info text 12px
Colors
Property Description --primer-color-text-primaryPrimary text color --primer-color-text-secondarySecondary text (card details) --primer-color-text-disabledDisabled text --primer-color-icon-primaryPayment method icons
Borders & Backgrounds
Property Description --primer-color-border-outlined-defaultCard item border --primer-color-border-outlined-selectedSelected card border --primer-color-background-outlined-defaultCard item background --primer-color-background-outlined-hoverHover background --primer-radius-mediumCard item border radius
Delete Confirmation
Property Description --primer-color-red-100Warning background --primer-color-red-500Delete button color --primer-color-text-negativeWarning text
Animation
Property Description Default --primer-animation-durationTransition duration 200ms--primer-animation-easingTransition 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
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