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.
Endpoint Actions
Create Record
POST /v2/accountvaults
Required Fields for Account Vault Creation by Payment Method
| ALL | CC | ACH |
|---|---|---|
|
|
|
Example 1: Create Credit Card Account Vault (CC)
{
"accountvault": {
"title": "Test CC Account",
"payment_method": "cc", // Required
"account_holder_name": "John Smith",
"account_number":"5454545454545454", // Required
"exp_date": "0919", // Required for "cc"
"contact_id": "54c285f1-678d-9510-318c-bcb13ab0c1c2",
"location_id": "sd9fusd9f-678d-9510-318c-bcb13ab4324" // Required
}
}
{
"accountvault": {
"id": "54c285f1-8052-06b4-318c-f1a9ebf8a288",
"payment_method": "cc",
"title": "Test CC Account",
"account_holder_name": "John Smith",
"first_six": "545454",
"last_four": "5454",
"billing_address": null,
"billing_zip": null,
"exp_date": "0919",
"routing": null,
"account_type": "mc",
"location_id": "sd9fusd9f-678d-9510-318c-bcb13ab4324",
"contact_id": "54c285f1-678d-9510-318c-bcb13ab0c1c2",
"created_ts": 1422037632,
"modified_ts": 1422037632,
"account_vault_api_id": null,
"dl_number": null,
"dl_state": null,
"customer_id": null,
"ssn4": null,
"dob_year": null,
"billing_state": null,
"billing_city": null,
"billing_phone": null,
"accountvault_c1": null,
"accountvault_c2": null,
"accountvault_c3": null,
"expiring_in_months": 12,
"has_recurring": false,
"ach_sec_code": null,
"active": 1,
"_links": {
"self": {
"href": "{url}/v2/accountvaults/54c285f1-8052-06b4-318c-f1a9ebf8a288"
}
}
}
}
Example 2: Create a BANK Account Vault (ACH)
{
"accountvault": {
"title": "Test ACH Account",
"payment_method": "ach", // Required
"account_holder_name": "John Smith",
"account_number":"700953657", // Required
"account_type": "checking", // Required for "ach"
"is_company": false, // Required for "ach"
"routing": "100020200", // Required for "ach"
"contact_id": "54c285f1-678d-9510-318c-bcb13ab0c1c2",
"location_id": "sd9fusd9f-678d-9510-318c-bcb13ab4324" // Required
}
}
{
"accountvault": {
"id": "54c285f1-8052-06b4-318c-f1a9ebf8a288",
"payment_method": "ach",
"title": "Test ACH Account",
"account_holder_name": "John Smith",
"first_six": "700953",
"last_four": "3657",
"billing_address": null,
"billing_zip": null,
"exp_date": null,
"routing": null,
"account_type": "checking",
"location_id": "sd9fusd9f-678d-9510-318c-bcb13ab4324",
"contact_id": "54c285f1-678d-9510-318c-bcb13ab0c1c2",
"created_ts": 1422037632,
"modified_ts": 1422037632,
"account_vault_api_id": null,
"dl_number": null,
"dl_state": null,
"customer_id": null,
"ssn4": null,
"dob_year": null,
"billing_state": null,
"billing_city": null,
"billing_phone": null,
"accountvault_c1": null,
"accountvault_c2": null,
"accountvault_c3": null,
"expiring_in_months": null,
"has_recurring": false,
"ach_sec_code": "WEB",
"active": 1,
"_links": {
"self": {
"href": "{url}/v2/accountvaults/54c285f1-8052-06b4-318c-f1a9ebf8a288"
}
}
}
}
Creating an account using Ticket
POST /v2/accountvaults
{
"accountvault":{
"payment_method":"cc", // Required
"ticket":"123456789", // Required when creating from Ticket
"location_id":"11111-11111-11111-11111", // Required
"contact_id":"22222-22222-22222-22222",
"title": "CC Account from Ticket"
}
}
{
"accountvault": {
"id": "54c285f1-8052-06b4-318c-f1a9ebf8a288",
"payment_method": "cc",
"title": "CC Account from Ticket",
"account_holder_name": null,
"first_six": "555555",
"last_four": "5555",
"billing_address": null,
"billing_zip": "12345",
"exp_date": "0919",
"routing": null,
"account_type": "mc",
"location_id": "sd9fusd9f-678d-9510-318c-bcb13ab4324",
"contact_id": "54c285f1-678d-9510-318c-bcb13ab0c1c2",
"created_ts": 1422037632,
"modified_ts": 1422037632,
"account_vault_api_id": null,
"dl_number": null,
"dl_state": null,
"customer_id": null,
"ssn4": null,
"dob_year": null,
"billing_state": null,
"billing_city": null,
"billing_phone": null,
"accountvault_c1": null,
"accountvault_c2": null,
"accountvault_c3": null,
"expiring_in_months": 12,
"has_recurring": false,
"ach_sec_code": null,
"active": 1,
"_links": {
"self": {
"href": "{url}/v2/accountvaults/54c285f1-8052-06b4-318c-f1a9ebf8a288"
}
}
}
}
Create from Previous Transaction
POST /v2/accountvaults
Required fields for Account Vault creation from previous transaction
- previous_transaction_id
- payment_method
- location_id
{
"accountvault": {
"title": "CC Account from Trx", // Optional
"payment_method": "cc", // Required
"previous_transaction_id": "{transaction_id}", // Required when creating from Previous Transaction
"contact_id": "{contact_id}",
"location_id": "{location_id}"// Required
}
}
{
"accountvault": {
"id": "54c285f1-8052-06b4-318c-f1a9ebf8a288",
"payment_method": "cc",
"title": "CC Account from Trx",
"account_holder_name": null,
"first_six": "555555",
"last_four": "5555",
"billing_address": null,
"billing_zip": "12345",
"exp_date": "0919",
"routing": null,
"account_type": "mc",
"location_id": "sd9fusd9f-678d-9510-318c-bcb13ab4324",
"contact_id": "54c285f1-678d-9510-318c-bcb13ab0c1c2",
"created_ts": 1422037632,
"modified_ts": 1422037632,
"account_vault_api_id": null,
"dl_number": null,
"dl_state": null,
"customer_id": null,
"ssn4": null,
"dob_year": null,
"billing_state": null,
"billing_city": null,
"billing_phone": null,
"accountvault_c1": null,
"accountvault_c2": null,
"accountvault_c3": null,
"expiring_in_months": 12,
"has_recurring": false,
"ach_sec_code": null,
"active": 1,
"_links": {
"self": {
"href": "{url}/v2/accountvaults/54c285f1-8052-06b4-318c-f1a9ebf8a288"
}
}
}
}
Update Record
PUT /v2/accountvaults/{id}
-or-
PUT /v2/accountvaults/{api_id}?api_id=1&location_id={location_id}
{
"accountvault": {
"exp_date": "0921"
}
}
{
"accountvault": {
"id": "54c285f1-8052-06b4-318c-f1a9ebf8a288",
"payment_method": "cc",
"title": "CC Account from Trx",
"account_holder_name": null,
"first_six": "555555",
"last_four": "5555",
"billing_address": null,
"billing_zip": "12345",
"exp_date": "0921",
"routing": null,
"account_type": "mc",
"location_id": "sd9fusd9f-678d-9510-318c-bcb13ab4324",
"contact_id": "54c285f1-678d-9510-318c-bcb13ab0c1c2",
"created_ts": 1422037632,
"modified_ts": 1422037632,
"account_vault_api_id": null,
"dl_number": null,
"dl_state": null,
"customer_id": null,
"ssn4": null,
"dob_year": null,
"billing_state": null,
"billing_city": null,
"billing_phone": null,
"accountvault_c1": null,
"accountvault_c2": null,
"accountvault_c3": null,
"expiring_in_months": 36,
"has_recurring": false,
"ach_sec_code": null,
"active": 1,
"_links": {
"self": {
"href": "{url}/v2/accountvaults/54c285f1-8052-06b4-318c-f1a9ebf8a288"
}
}
}
}
View Single Record
GET /v2/accountvaults/{id}
-or-
GET /v2/accountvaults/{api_id}?api_id=1&location_id={location_id}
{
// Empty Payload - Nothing Needed Here
}
{
"accountvault": {
"id": "54c285f1-8052-06b4-318c-f1a9ebf8a288",
"payment_method": "cc",
"title": "CC Account from Trx",
"account_holder_name": null,
"first_six": "555555",
"last_four": "5555",
"billing_address": null,
"billing_zip": "12345",
"exp_date": "0919",
"routing": null,
"account_type": "mc",
"location_id": "sd9fusd9f-678d-9510-318c-bcb13ab4324",
"contact_id": "54c285f1-678d-9510-318c-bcb13ab0c1c2",
"created_ts": 1422037632,
"modified_ts": 1422037632,
"account_vault_api_id": null,
"dl_number": null,
"dl_state": null,
"customer_id": null,
"ssn4": null,
"dob_year": null,
"billing_state": null,
"billing_city": null,
"billing_phone": null,
"accountvault_c1": null,
"accountvault_c2": null,
"accountvault_c3": null,
"expiring_in_months": 12,
"has_recurring": false,
"ach_sec_code": null,
"active": 1,
"_links": {
"self": {
"href": "{url}/v2/accountvaults/54c285f1-8052-06b4-318c-f1a9ebf8a288"
}
}
}
}
View Record List
GET /v2/accountvaults
Note:
- 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.
{
// Empty Payload - Nothing Needed here
}
{
"accountvaults": [
{
"id": "54c285f1-8052-06b4-318c-f1a9ebf8a288",
"payment_method": "cc",
"title": "CC Account from Trx",
"account_holder_name": null,
"first_six": "555555",
"last_four": "5555",
"billing_address": null,
"billing_zip": "12345",
"exp_date": "0919",
"routing": null,
"account_type": "mc",
"location_id": "sd9fusd9f-678d-9510-318c-bcb13ab4324",
"contact_id": "54c285f1-678d-9510-318c-bcb13ab0c1c2",
"created_ts": 1422037632,
"modified_ts": 1422037632,
"account_vault_api_id": null,
"dl_number": null,
"dl_state": null,
"customer_id": null,
"ssn4": null,
"dob_year": null,
"billing_state": null,
"billing_city": null,
"billing_phone": null,
"accountvault_c1": null,
"accountvault_c2": null,
"accountvault_c3": null,
"expiring_in_months": 12,
"has_recurring": false,
"ach_sec_code": null,
"active": 1,
"_links": {
"self": {
"href": "{url}/v2/accountvaults/54c285f1-8052-06b4-318c-f1a9ebf8a288"
}
}
},
// Other Account Vaults Here
],
"meta": {
"pagination": {
"links": {
"self": {
"href": "{url}/v2/accountvaults?contact_id=54c285f1-678d-9510-318c-bcb13ab0c1b4&page_size=3&page=1"
}
},
"totalCount": 1,
"pageCount": 1,
"currentPage": 0,
"perPage": 3
},
"sort": {
"attributes": {
"id": "desc"
}
}
}
}
Delete Record
DELETE /v2/accountvaults/{id}
-or-
DELETE /v2/accountvaults/{api_id}?api_id=1&location_id={location_id}
{
// Empty Payload - Nothing Needed Here
}
Response will be conditional on HTTP Response Code: 204 - Success, No JSON Response 422 - Fail, JSON will contain validation error
Get BIN Info
GET /v2/accountvaults/{id}/bininfo
{
"bininfo": {
"issuer_bank_name": "Cartasi S.P.A.",
"country_code": "ITA",
"detail_card_product": "V",
"detail_card_indicator": "X",
"fsa_indicator": "",
"prepaid_indicator": "",
"product_id": "G",
"regulator_indicator": "N",
"visa_product_sub_type": "",
"visa_large_ticket_indicator": "",
"account_fund_source": "C",
"card_class": "B",
"token_ind": "",
"issuing_network": null
}
}
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.
Fields
| Name | Min | Max | Format | POST Required |
Post Allowed |
PUT Allowed |
Comments |
|---|---|---|---|---|---|---|---|
| account_holder_name | 1 | 32 | string | ✔ | ✔ | ✔ |
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'. |
| account_number | 4 | 19 | string | ✔ | ✔ |
For CC transactions, a credit card number. |
|
| account_type | 1 | 32 | string | ✔ |
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. | ||
| run_avs | 1 | 1 | boolean | ✔ |
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 | 1 | integer | ✔ | ✔ | Terms agreement. | ||
| 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.
| Related Record | Expand |
|---|---|
| Location | location |
| Contact | contact |
| Signature | signature |
| Created User | created_user |
| Product Transaction | product_transaction |
| 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:
/v2/accountvaults/xxxxxxxxxxxxxxxxxxxxxxxx?expand=location
To use multiple expands on this endpoint, simply include them both separated by a comma like so:
/v2/accountvaults/xxxxxxxxxxxxxxxxxxxxxxxx?expand=location,created_user