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.

1
{
2
  "mid": "800000001780",
3
  "amount": "10.00",
4
  "account_token": "4444333322221111",
5
  "expiration": "202911",
6
  "vault": "Y",
7
  "name": "John Doe",
8
  "capture": "Y",
9
  "p_account_zip": "19064",
10
  "cvn": "555"
11
}

The response will include the vault_holder_id:

1
{
2
  "trans_id": "12345678",
3
  "vault_id": 123456,
4
  "vault_holder_id": "5b04a646-b49d-4505-b3fc-bd4062c10662",
5
  "result": "A",
6
  "resp_text": "APPROVED"
7
}

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

1
{
2
  "mid": "800000001780",
3
  "amount": "0.00",
4
  "vault_holder_id": "5b04a646-b49d-4505-b3fc-bd4062c10662",
5
  "account_token": "4444333322221111",
6
  "expiration": "202911",
7
  "vault": "Y",
8
  "name": "John Doe",
9
  "capture": "N",
10
  "p_account_zip": "19064",
11
  "cvn": "555",
12
  "custom_01": "asd",
13
  "custom_02": "ddd",
14
  "custom_03": "fff"
15
}

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 - Process payments and manage vaults
• Update Vault Payment Account - Update existing vaulted payment information

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