Account Vaults Endpoint
The accountvaults endpoint is used as a tokenization endpoint to store account vault records. If there is a need to store accountvaults (tokens) for account numbers and card numbers for later use, then this is the endpoint to perform that task.
The account_vault_id field can be used in place of the account_number and exp_date fields on most endpoints in the system. So storing an accountvault on this endpoint will allow for the reuse of the account at a later time.
Required Fields for Account Vault Creation by Payment Method
Example 1: Create Credit Card Account Vault (CC)
Example 2: Create a BANK Account Vault (ACH)
Creating an account using Ticket
Create from Previous Transaction
Required fields for Account Vault creation from previous transaction
View Single Record
View Record List
- Filters can be used to search for accounts by including the columns you want to filter on as URL parameters.
- Expands can be used to include additional data associated with an Account Vault. See Expands further below for more details.
Get BIN Info
BIN Info Fields
For more information on BIN Info including the purpose of each field returned and the possible values for each take a look at our BIN Info documentation.
For CC, this is the "Name (as it appears) on Card".
Required for POST when payment_method is 'ach'. Not required when payment_method is 'cc'.
For CC transactions, a credit card number.
For ACH, must be provided as either “checking” or “savings”.
|account_vault_api_id||1||36||string||✔||✔||Optional. Must be unique per location. This field can be used to correlate Account Vaults in our system to data within an outside software integration. In addition, when running a transaction and using a stored account vault, this field can be used in place of account_vault_id.|
|accountvault_c1||128||string||✔||✔||Custom field 1 for API users to store custom data|
|accountvault_c2||128||string||✔||✔||Custom field 2 for API users to store custom data|
|accountvault_c3||128||string||✔||✔||Custom field 3 for API users to store custom data|
|ach_sec_code||3||string||✔||✔||SEC code for the account|
|billing_address||1||32||string||✔||✔||The Street portion of the address associated with the Credit Card (CC) or Bank Account (ACH).|
|billing_city||1||36||string||✔||✔||The City portion of the address associated with the Credit Card (CC) or Bank Account (ACH).|
|billing_phone||1||10||string||✔||✔||The Phone # to be used to contact Payer if there are any issues processing a transaction.|
|billing_state||2||2||string||✔||✔||The State portion of the address associated with the Credit Card (CC) or Bank Account (ACH).|
|billing_zip||5||10||string||✔||✔||The Zip or "Postal Code" portion of the address associated with the Credit Card (CC) or Bank Account (ACH).|
|contact_id||24||36||string||✔||✔||Used to associate the Account Vault with a Contact.|
|created_ts||10||10||integer||Created Timestamp. System will generate a value for this field automatically.|
|customer_id||1||50||string||✔||✔||Used to store a customer identification number.|
|dl_number||1||50||string||✔||✔||Used for certain ACH transactions where Driver's License is required by the terminal being used. When providing dl_number, dl_state must also be provided.|
|dl_state||2||2||string||✔||✔||Used for certain ACH transactions where Driver's License is required by the terminal being used. When providing dl_state, dl_number must also be provided.|
|dob_year||4||4||string||✔||Used for certain ACH transactions where Identity Verification is enabled on the terminal being used.|
|expiring_in_months||integer||Determined by API based on card exp_date.|
|exp_date||4||4||string||✔||✔||Required for CC. The Expiration Date for the credit card. (MMYY format).|
|first_six||6||6||integer||The first six numbers of an account number. System will generate a value for this field automatically.|
|has_recurring||boolean||True indicates that this account vault is tied to a Recurring Payment|
|id||24||36||string||A unique, system-generated identifier for the Account Vault.|
|is_company||1||1||boolean||✔||Required for ACH. This identifies whether the ACH account belongs to a company or individual. This can affect which SEC code is used when attempting to run a transaction.
For CC, this field is ignored.
|last_four||4||4||integer||The last four numbers of an account number. System will generate a value for this field automatically.|
|location_id||24||36||string||✔||✔||A valid Location Id associated with the Contact for this Account Vault.|
|modified_ts||10||10||integer||Modified Timestamp. System will generate a value for this field automatically.|
|payment_method||2||3||string||✔||✔||Must be provided as either 'cc' or 'ach'.|
|previous_account_vault_api_id||64||string||✔||Can be used to pull payment info from a previous account vault api id.|
|previous_account_vault_id||24||36||string||✔||Can be used to pull payment info from a previous account vault.|
|previous_transaction_id||24||36||string||✔||Can be used to pull payment info from a previous transaction.|
|routing||9||9||string||✔||Required for ACH. The Routing Number for the bank account being used.|
A flag that will override a product transactions run_avs_on_accountvault_create setting to determine if an avsonly transaction should be run prior to storing the account vault. When storing an account vault with tha run_avs flag, if the avsonly check fails account verification with the processor, the account vault will not be stored in the system. The meaning of the AVS response codes can be found here on this page.
This is the new preferred method of validating a credit card and can be used instead of the legacy $1 auth only transaction.Using this flag overrides the default setting for the locations product transactions.
NOTE: Transaction fees may apply when performing an avsonly transaction while storing an account vault.
|ssn4||4||string||✔||✔||The last four of the account_holder social security number.|
|terms_agree_ip||15||string||✔||✔||The ip address of the client that agreed to terms.|
|ticket||1||36||string||✔||A valid ticket that was created to store the accountvault.|
|title||1||16||string||✔||✔||Used to describe the Account Vault for easier identification within our UI.|
|track_data||256||string||✔||Track Data from a magnetic card swipe.|
Expands (Related Records)
For detail on how to use Expands on an Endpoint, please visit the Expands (Related Records) page.
|Account Vault Card Account Updates Product Transaction||account_vault_cau_product_transaction|
|Account Vault Card Account Update Logs||account_vault_cau_logs|
An example of “expanding” this endpoint to one of the above related records would look like this:
To use multiple expands on this endpoint, simply include them both separated by a comma like so: