# Vault

Create reusable payment experiences using securely stored payment methods.

Store payment credentials securely using tokenized payment references instead of sensitive payment data.

Create and manage customer profiles, associate payment methods with customers, and reuse stored payment methods across future payment workflows.

Customer Vault stores and manages reusable payment credentials, while recurring payments use those stored credentials to automate future payment execution.

### Why Use Vault?

Vault enables developers to:

- Store reusable payment credentials securely.
- Support returning customers without re-entering payment information.
- Enable recurring billing and subscription payment scenarios.
- Support card-on-file payment experiences.
- Maintain customer-to-payment-method relationships.
- Reduce exposure to sensitive payment data through tokenization.


Common use cases include:

- Returning customer checkout
- Subscription billing
- Membership payments
- Card-on-file transactions
- Saved ACH payment methods
- Platform and ISV payment experiences


### Core Concepts

#### Customer

A customer acts as the container for one or more stored payment methods.

In Experience APIs, the customer identifier maps to the Vault Key used by hosted and embedded payment experiences.

#### Payment Method

A payment method represents a specific stored payment credential associated with a customer.

A customer may have multiple stored payment methods.

In hosted and embedded payment experiences, the payment method identifier maps to the Vault ID returned after storing the credential.

#### Vault Identifier Mapping

| Concept | API | Hosted Payment Form | Embedded Payments |
|  --- | --- | --- | --- |
| Customer Identifier | Customer ID | Customer ID | Customer Token |
| Payment Method Identifier | Payment Method ID | Vault ID | Vault ID |


### Store Payment Methods

Stored payment methods allow merchants and platforms to save customer payment credentials for future use.

Rather than storing raw payment credentials, applications should store vault references and tokenized payment information.

#### Supported Use Cases

- Save a payment method for future purchases.
- Returning customer checkout.
- Recurring billing.
- Subscription payments.
- Card-on-file transactions.
- ACH payment storage for supported future transactions.
- Platform and ISV payment experiences.


#### Storage Workflow

The vault storage workflow shows how payment credentials are collected during checkout, tokenized for security, associated with a customer and stored in the vault, and then referenced for future payment transactions.

**Collect Payment Information**
Collect payment credentials during supported checkout experiences.

**Tokenize Credentials**
Create a token to represent the underlying payment account.

**Create Vault Record**
Associate the tokenized payment with a customer and store the payment in the vault.

**Reuse Stored Credentials**
Reference the stored payment credentials for future transactions.

For implementation workflows, API usage, and examples, see [**Store a Payment Method Integration Guide →**](/products/merchant-services/developer-resources/developer-guide/store-payment-method-integration)

### Customer Profiles

Customer Profiles provide a centralized representation of a customer and the customer's associated payment methods.

Customer records act as containers that organize stored payment credentials and supporting metadata.

#### What a Customer Profile Contains

- Customer identifier
- Associated payment methods
- Vault relationships
- Customer metadata (where supported)
- References used by recurring and future payment workflows


#### Customer Relationship Model

The vault customer relationship model shows how a stored customer profile is associated with multiple payment methods. Each payment method has its own tokenization credential that represents the stored payment information.

- **Stored Customer Data:** The customer profile stores the customer identifier, associated payment methods, vault relationships, and supporting metadata.
- **Customer Records:** A customer profile can be associated with multiple payment methods.
- **Payment Methods:** Each stored payment method represents a payment option associated with the customer profile.
- **Tokenization Credentials:** Each payment method is associated with its own tokenization credential.


### Payment Method Lifecycle

Stored payment methods and customer records are managed throughout their lifecycle.

| Operation | Description |
|  --- | --- |
| Create | If a vaulted payment method does not have a billing address associated with it, the billing address stored at the customer level will be used and sent with the transaction request. |
| Retrieve | Retrieve customer profile information, stored payment methods, and vault relationships using customer and vault-related APIs. |
| Update | Modify stored payment information while preserving existing vault references. Typical updates include replacing payment credentials, updating expiration dates, and updating payment methods associated with subscriptions or future payments. |
| Delete | Remove customer records, stored payment methods, associated metadata, and related vault relationships. Existing transaction records remain but are no longer associated with the deleted customer. |


Customer API →
Payment Method API →
### Best Practices

#### Recommended

- Store vault references instead of payment credentials.
- Reuse existing payment methods when appropriate.
- Support customer payment method updates.
- Tokenize payment information as early as possible.
- Maintain accurate customer-to-payment-method relationships.
- Use stored payment methods for future and recurring payment experiences.


#### Avoid

- Storing card numbers directly.
- Storing bank account numbers directly.
- Creating a new stored credential for every transaction.
- Assuming vault references can be shared across merchants without validating scope and configuration requirements.


### Related Resources

Implement Vault
Learn how to create customer profiles and store payment methods using supported APIs and payment experiences.

Payment Methods
Learn about supported payment methods that can be stored and reused.

Recurring Payments
Use stored payment methods to automate future payment execution.