Customer Vault

Overview

The Customer Vault enables merchants to securely store customer payment information in a Level 1 PCI certified data facility without maintaining cardholder data locally. This addresses Payment Card Industry (PCI) Data Security Standard requirements and shifts liability to the gateway provider.

Store payment data securely and initiate transactions using stored credentials without handling raw card data.

Benefits

PCI Compliance

Reduce PCI scope by not storing card data

Recurring Billing

Process automatic recurring payments

Quick Checkout

Enable one-click payments for returning customers

Multiple Payment Methods

Store cards, bank accounts, and digital wallets

API Endpoint

POST https://api.ionicfi.com/api/transact.php

Core Operations

Add Customer
Update Customer
Delete Customer

Create a new customer record in the vault.

security_key=YOUR_API_KEY
customer_vault=add_customer
ccnumber=4111111111111111
ccexp=1225
cvv=999
first_name=John
last_name=Doe
address1=123 Main St
city=New York
state=NY
zip=10001

Response:

response=1&responsetext=SUCCESS&customer_vault_id=123456

Modify an existing customer record.

security_key=YOUR_API_KEY
customer_vault=update_customer
customer_vault_id=123456
ccexp=1226
address1=456 New Address

Response:

response=1&responsetext=Customer Update Successful

Remove a customer record from the vault.

security_key=YOUR_API_KEY
customer_vault=delete_customer
customer_vault_id=123456

Response:

response=1&responsetext=Customer Deleted

Adding Payment Methods

Credit/Debit Cards

<?php
$url = "https://api.ionicfi.com/api/transact.php";

$data = array(
    "security_key" => "YOUR_API_KEY",
    "customer_vault" => "add_customer",
    "ccnumber" => "4111111111111111",
    "ccexp" => "1225",
    "cvv" => "999",
    "first_name" => "John",
    "last_name" => "Doe",
    "address1" => "123 Main St",
    "city" => "New York",
    "state" => "NY",
    "zip" => "10001",
    "email" => "[email protected]",
    "phone" => "555-1234"
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

parse_str($response, $result);
echo "Customer Vault ID: " . $result['customer_vault_id'];
?>

ACH/Bank Accounts

security_key=YOUR_API_KEY
customer_vault=add_customer
checkname=John Doe
checkaba=123456789
checkaccount=987654321
account_type=checking
sec_code=WEB
first_name=John
last_name=Doe

With Collect.js Token

security_key=YOUR_API_KEY
customer_vault=add_customer
payment_token=TOKEN_FROM_COLLECTJS
first_name=John
last_name=Doe

With Digital Wallets

Apple Pay:

security_key=YOUR_API_KEY
customer_vault=add_customer
applepay_payment_data=ENCRYPTED_TOKEN

Google Pay:

security_key=YOUR_API_KEY
customer_vault=add_customer
googlepay_payment_data=ENCRYPTED_PAYLOAD

Auto-Generated IDs

If you don’t specify a customer_vault_id, the system will auto-generate one:

# Without ID - system generates
customer_vault=add_customer

# With custom ID
customer_vault=add_customer
customer_vault_id=CUSTOM_ID_123

Custom IDs must be unique across your merchant account. Use auto-generation for simplicity.

Transacting with Stored Credentials

Once payment information is stored, initiate transactions using the customer vault ID:

Sale Transaction

security_key=YOUR_API_KEY
type=sale
customer_vault_id=123456
amount=50.00

Authorization

security_key=YOUR_API_KEY
type=auth
customer_vault_id=123456
amount=50.00

Credit

security_key=YOUR_API_KEY
type=credit
customer_vault_id=123456
amount=25.00

Validation

security_key=YOUR_API_KEY
type=validate
customer_vault_id=123456

Stored Credential Compliance

When storing payment credentials, implement the Credential on File (CoF) framework:

Initial Transaction

First transaction must include stored_credential_indicator: 'stored'

stored_credential_indicator=stored
initiated_by=customer

Store Transaction ID

Save the transactionid from the gateway response

Subsequent Transactions

Use stored_credential_indicator: 'used' with original transaction ID

stored_credential_indicator=used
initial_transaction_id=ORIGINAL_TXN_ID
initiated_by=merchant

Initial Storage Example

security_key=YOUR_API_KEY
type=sale
amount=25.00
ccnumber=4111111111111111
ccexp=1225
cvv=999
customer_vault=add_customer
stored_credential_indicator=stored
initiated_by=customer

Subsequent Transaction Example

security_key=YOUR_API_KEY
type=sale
amount=30.00
customer_vault_id=123456
stored_credential_indicator=used
initial_transaction_id=987654321
initiated_by=merchant

Card brand matching is enforced between initial and subsequent transactions. You cannot use a Visa token to charge a Mastercard.

Customer Vault Variables

Required Fields

Variable	Description
`security_key`	Your API security key
`customer_vault`	Action: `add_customer`, `update_customer`, `delete_customer`

Payment Fields (Add/Update)

Variable	Description	Format
`ccnumber`	Credit card number	Numeric
`ccexp`	Expiration date	MMYY
`cvv`	Security code	Numeric
`checkname`	Account holder name	String
`checkaba`	Routing number	Numeric
`checkaccount`	Account number	Numeric
`account_type`	`checking` or `savings`	String
`payment_token`	Collect.js token	String

Billing Information

Variable	Description
`first_name`	Customer first name
`last_name`	Customer last name
`company`	Company name
`address1`	Street address line 1
`address2`	Street address line 2
`city`	City
`state`	State/province code
`zip`	Postal code
`country`	Country code
`phone`	Phone number
`email`	Email address

Shipping Information

Prefix all address fields with shipping_:

shipping_firstname=Jane
shipping_lastname=Smith
shipping_address1=456 Shipping St

Multiple Payment Methods

Store multiple payment methods per customer using billing IDs:

# Add primary payment method
customer_vault=add_customer
customer_vault_id=CUST123
ccnumber=4111111111111111
ccexp=1225

# Add second payment method
customer_vault=add_billing
customer_vault_id=CUST123
billing_id=BILLING2
ccnumber=5424000000000015
ccexp=1226

Update Operations

Update Payment Method

security_key=YOUR_API_KEY
customer_vault=update_customer
customer_vault_id=123456
ccexp=1227
cvv=123

Update Billing Information

security_key=YOUR_API_KEY
customer_vault=update_customer
customer_vault_id=123456
address1=789 New St
city=Los Angeles
state=CA
zip=90001

Security Best Practices

Never Store CVV

CVV values cannot be stored per PCI DSS. Only submit during add/update operations.

Attempting to store CVV long-term violates PCI compliance.

Use HTTPS Only

Always use HTTPS for API requests. Never transmit payment data over HTTP.

Implement Access Controls

Restrict access to customer vault operations:

Separate API keys for vault operations
Log all vault access
Implement multi-factor authentication

Regular Audits

Periodically review stored credentials:

Remove inactive customers
Update expired cards
Verify data integrity

Error Handling

Common customer vault errors:

Error	Description	Resolution
`Invalid customer vault id`	ID doesn’t exist	Verify ID or create new customer
`Duplicate customer vault id`	ID already exists	Use different ID or update existing
`Invalid card number`	Card number validation failed	Verify card number format
`Card expired`	Expiration date in past	Update with valid expiration

Next Steps

Payment API

Process transactions with stored data

Recurring Billing

Set up automatic payments

Collect.js

Tokenize before storing

Query API

Retrieve customer information

Getting Started

Integration Methods

Partners

API Reference

​Overview

​Benefits

PCI Compliance

Recurring Billing

Quick Checkout

Multiple Payment Methods

​API Endpoint

​Core Operations

​Adding Payment Methods

​Credit/Debit Cards

​ACH/Bank Accounts

​With Collect.js Token

​With Digital Wallets

​Auto-Generated IDs

​Transacting with Stored Credentials

​Sale Transaction

​Authorization

​Credit

​Validation

​Stored Credential Compliance

​Initial Storage Example

​Subsequent Transaction Example

​Customer Vault Variables

​Required Fields

​Payment Fields (Add/Update)

​Billing Information

​Shipping Information

​Multiple Payment Methods

​Update Operations

​Update Payment Method

​Update Billing Information

​Security Best Practices

​Error Handling

​Next Steps

Payment API

Recurring Billing

Collect.js

Query API

Overview

Benefits

API Endpoint

Core Operations

Adding Payment Methods

Credit/Debit Cards

ACH/Bank Accounts

With Collect.js Token

With Digital Wallets

Auto-Generated IDs

Transacting with Stored Credentials

Sale Transaction

Authorization

Credit

Validation

Stored Credential Compliance

Initial Storage Example

Subsequent Transaction Example

Customer Vault Variables

Required Fields

Payment Fields (Add/Update)

Billing Information

Shipping Information

Multiple Payment Methods

Update Operations

Update Payment Method

Update Billing Information

Security Best Practices

Error Handling

Next Steps