> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runpayments.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runpayments.io/_mcp/server.

# Vaults

# Vaults & Customers Overview

Vaults allow you to securely store customer payment information for future transactions without the need to re-enter payment details. This guide covers how to create and manage vaulted customers and their associated payment methods.

The vault system enables you to:

* Create vaulted customers to store payment information securely
* Add multiple payment methods to existing vaulted customers
* Process transactions using stored payment methods
* Update customer and payment method details

## Creating a Vault

When you want to vault a customer's payment information, include the `vault` parameter set to `"Y"` in your charge request. This will create a new vault entry and return a `vault_holder_id` that you can use for future transactions.

```json
{
  "mid": "800000001780",
  "amount": "10.00",
  "account_token": "4444333322221111",
  "expiration": "202911",
  "vault": "Y",
  "name": "John Doe",
  "capture": "Y",
  "p_account_zip": "19064",
  "cvn": "555"
}
```

The response will include the `vault_holder_id`:

```json
{
  "trans_id": "12345678",
  "vault_id": 123456,
  "vault_holder_id": "5b04a646-b49d-4505-b3fc-bd4062c10662",
  "result": "A",
  "resp_text": "APPROVED"
}
```

## Adding Payment Methods to Existing Vaults

You can add additional payment methods to a preexisting vaulted customer by including the `vault_holder_id` in your charge request. This allows you to associate multiple payment methods with a single customer vault.

### Zero-Dollar Authorization

To add a new payment method without capturing funds, you can perform a \$0 authorization by setting the amount to `"0.00"` and `capture` to `"N"`:

```json
{
  "mid": "800000001780",
  "amount": "0.00",
  "vault_holder_id": "5b04a646-b49d-4505-b3fc-bd4062c10662",
  "account_token": "4444333322221111",
  "expiration": "202911",
  "vault": "Y",
  "name": "John Doe",
  "capture": "N",
  "p_account_zip": "19064",
  "cvn": "555",
  "custom_01": "asd",
  "custom_02": "ddd",
  "custom_03": "fff"
}
```

This approach:

* Validates the payment method without charging the customer
* Adds the payment method to the existing vault holder
* Returns a new `vault_id` for the added payment method

## Using Vaulted Payment Methods

Once you have vaulted payment methods, you can process transactions using either:

* The `vault_id` for a specific payment method
* The `vault_holder_id` along with payment method details

## Best Practices

1. **Security**: Always use vault functionality when storing customer payment information to ensure PCI compliance
2. **Validation**: Use \$0 authorizations to validate new payment methods before storing them
3. **Organization**: Use the vault holder system to group multiple payment methods per customer
4. **Custom Fields**: Utilize custom fields to store additional customer or transaction metadata

## Related Endpoints

* [Charge API](/reference/payments-api/process-charge) - Process payments and manage vaults
* [Update Vault Payment Account](/reference/payments-api/update-vault-payment-account) - Update existing vaulted payment information

For more information on implementing vault functionality, see the charge endpoint documentation.