Customer Vault

TIP

This section describes the canonical methods for creating and managing Customer records. The endpoints described in the Customers (Deprecated) section are still available for use, but be advised that using endpoints from both groups in your application simultaneously can result in unintended behaviors.

Create Customer Record

Creates a new Customer record that can contain stored preferences, payment methods, and addresses.

Request Method: POST

URL Endpoint: /api/vault/customer

Name	Type	Default	Description	Required
id	string	generated value	Optionally, you may provide a custom id for storing the vaulted customer. Max 40 characters (a-z, A-Z, 0-9)
id_format	string literal		Optionally defines a format for the gateway to use when auto-generating an id ("xid_type_last4"). Cannot be used if providing a custom id.
description	string	""	Text field, max 255 characters
flags	string array	[]	Array containing flags for customer settings ("surcharge_exempt")
default_payment	object	null	Object containing ach payment method details
default_payment .card	object	null	Object containing card payment method details
default_payment .card .number	string	""	Card number
default_payment .card .expiration_date	string	""	Card expiration date ("MMYY" or "MM/YY")	required if `default_payment.card` is present
default_payment .ach	object	null	Object containing ach payment method details
default_payment .ach .account_number	string	""	Account number
default_payment .ach .routing_number	string	""	Routing number
default_payment .ach .account_type	string literal		Ach account type ("checking" or "savings")	required if `default_payment.ach` is present
default_payment .ach .sec_code	string literal		Ach sec code ("web", "ccd", or "ppd")	required if `default_payment.ach` is present
default_payment .token	string		Payment method token generated by Tokenizer form
default_payment .apple_pay	object	null	Object containing Apple Pay payment method details
default_payment .apple_pay .key_id	string	""	Merchant Apple Pay ID	required if `default_payment.apple_pay` is present
default_payment .apple_pay .processor_id	string	""	Processor ID
default_payment .apple_pay .temporary_token	string	""	Token from WalletJS response	required if using WalletJS
default_payment .apple_pay .pkpaymenttoken	object	null	PKPaymentToken from Apple Pay JS response	required if using Apple Pay JS
default_payment .google_pay_token	object or string	null	Object or string containing a Google Pay token
default_billing_address	object	null	Object containing billing address details
default_billing_address .first_name	string	""	Addressee first name
default_billing_address .last_name	string	""	Addressee last name
default_billing_address .company	string	""	Company name
default_billing_address .line_1	string	""	Street address
default_billing_address .line_2	string	""	Additional delivery details
default_billing_address .city	string	""	City name
default_billing_address .state	string	""	State code ("CA")
default_billing_address .postal_code	string	""	Postal code ("12345")
default_billing_address .country	string	""	Country code ("US")
default_billing_address .email	string	""	Email address (must be valid email format, "example@mail.com")
default_billing_address .phone	string	""	Phone number ("3216540987")
default_billing_address .fax	string	""	("3216540987")
default_shipping_address	object	null	Object containing shipping address details
default_shipping_address .first_name	string	""	Addressee first name
default_shipping_address .last_name	string	""	Addressee last name
default_shipping_address .company	string	""	Company name
default_shipping_address .line_1	string	""	Street address
default_shipping_address .line_2	string	""	Additional delivery details
default_shipping_address .city	string	""	City name
default_shipping_address .state	string	""	State code ("CA")
default_shipping_address .postal_code	string	""	Postal code ("12345")
default_shipping_address .country	string	""	Country code ("US")
default_shipping_address .email	string	""	Email address (must be valid email format, "example@mail.com")
default_shipping_address .phone	string	""	Phone number ("3216540987")
default_shipping_address .fax	string	""	("3216540987")

Get Customer Record By ID

Retrieve details for the specified customer.

Request Method: GET

URL Endpoint: /api/vault/{ customer id }

json

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "952f250d-fa85-40ac-a45e-3886f98032c6",
    "owner_id": "testmerchant12345678",
    "data": {
      "customer": {
        "addresses": [
          {
            "city": "Some Town",
            "company": "Some Business",
            "country": "US",
            "email": "user@somesite.com",
            "fax": "555555555",
            "first_name": "John",
            "hash": "cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=",
            "id": "bl6nqk69ku6897l45fp0",
            "last_name": "Smith",
            "line_1": "",
            "line_2": "",
            "phone": "5555555555",
            "postal_code": "60187",
            "state": "IL"
          }
        ],
        "defaults": {
          "billing_address_id": "bl6nqk69ku6897l45fp0",
          "payment_method_id": "bl6nqk69ku6897l45fq0",
          "payment_method_type": "card",
          "shipping_address_id": "bl6nqk69ku6897l45fp0"
        },
        "description": "test description",
        "payments": {
          "ach": [],
          "cards": [
            {
              "card_type": "visa",
              "expiration_date': '2020-12-31T00:00:00Z',
              'id': 'bl6nqk69ku6897l45fq0',
              'masked_number': '411111******1111'
            }
          ]
        }
      }
    },
    "created_at": "2019-08-09T09:04:00.786094073-05:00",
    "updated_at": "2019-08-09T09:04:00.786094116-05:00"
  }
}

Search Customer Records

Retrieve details for all customer records that match provided search criteria.

Request Method: POST

URL Endpoint: /api/vault/customer/search

Name	Type	Default	Description
id	object		Object containing details defining a customer id to match or exclude
id .value	string	""	Customer record ID to match or exclude
id .operator	string	""	"=" or "!="
address_id	object		Object containing details defining an address id to match or exclude
address_id .value	string	""	Address ID to match or exclude
address_id .operator	string	""	"=" or "!="
first_name	object		Object containing details defining a customer first name to match or exclude
first_name .value	string	""	Customer first name to match or exclude
first_name .operator	string	""	"=" or "!="
last_name	object		Object containing details defining a customer last name to match or exclude
last_name .value	string	""	Customer last name to match or exclude
last_name .operator	string	""	"=" or "!="
company	object		Object containing details defining a company name to match or exclude
company .value	string	""	Customer company to match or exclude
company .operator	string	""	"=" or "!="
address_line_1	object		Object containing details defining a street address to match or exclude
address_line_1 .value	string	""	Customer street address to match or exclude
address_line_1 .operator	string	""	"=" or "!="
address_line_2	object		Object containing details defining additional address details to match or exclude
address_line_2 .value	string	""	Customer address details to match or exclude
address_line_2 .operator	string	""	"=" or "!="
city	object		Object containing details defining a city to match or exclude
city .value	string	""	Customer city to match or exclude
city .operator	string	""	"=" or "!="
state	object		Object containing details defining a state to match or exclude
state .value	string	""	Customer state to match or exclude
state .operator	string	""	"=" or "!="
postal_code	object		Object containing details defining a postal code to match or exclude
postal_code .value	string	""	Customer postal code to match or exclude
postal_code .operator	string	""	"=" or "!="
country	object		Object containing details defining a country to match or exclude
country .value	string	""	Customer country to match or exclude
country .operator	string	""	"=" or "!="
email	object		Object containing details defining a customer email to match or exclude
email .value	string	""	Customer email to match or exclude
email .operator	string	""	"=" or "!="
phone	object		Object containing details defining a phone number to match or exclude
phone .value	string	""	Customer phone to match or exclude
phone .operator	string	""	"=" or "!="
fax	object		Object containing details defining a fax number to match or exclude
fax .value	string	""	Customer fax to match or exclude
fax .operator	string	""	"=" or "!="
payment_method_type	object		Object containing details defining a payment method type to match or exclude
payment_method_type .value	string	""	Customer payment method type to match or exclude
payment_method_type .operator	string	""	"=" or "!="
billing_address_id	object		Object containing details defining a billing address id to match or exclude
billing_address_id .value	string	""	Customer billing address id to match or exclude
billing_address_id .operator	string	""	"=" or "!="
shipping_address_id	object		Object containing details defining a shipping address id to match or exclude
shipping_address_id .value	string	""	Customer shipping address id to match or exclude
shipping_address_id .operator	string	""	"=" or "!="
created_at	object		Object containing details defining a date range to match
created_at .start_date	string	""	Beginning of date range
created_at .end_date	string	""	End of date range
updated_at	object		Object containing details defining a date range to match
updated_at .start_date	string	""	Beginning of date range
updated_at .end_date	string	""	End of date range
limit	integer	10	The number of results to return (1-100)
offset	integer	0	The number of results to skip (1-1000)

Update Customer Record

Update an existing customer record.

Request Method: POST

URL Endpoint: /api/vault/customer/{ customer id }

Name	Type	Default	Description	Required
description	string	""	Text field, max 255 characters
notes	string	""	Text field, max 255 characters
flags	string array	[]	Array containing flags for customer settings ("surcharge_exempt")
defaults	object	null	Object containing id's designating payment methods and addresses to be used as defaults for the customer's transactions
defaults .billing_address_id	string	If only one stored address exists on the customer record, that will be used by default	Id of stored address to use as the default billing address for transactions
defaults .shipping_address_id	string	If only one stored address exists on the customer record, that will be used by default	Id of stored address to use as the default shipping address for transactions
defaults .payment_method_id	string		Id of stored payment method to use as the default payment method for transactions	required if `defaults.payment_method_type` is present
defaults .payment_method_type	string literal	""	Type of the payment method id supplied ("card" or "ach")	required if `defaults.payment_method_id` is present

Delete Customer Record

Delete the specified customer record.

Request Method: DELETE

URL Endpoint: /api/vault/{ customer id }

json

{
  "status": "success",
  "msg": "success"
}

Create Address Record

Create a new address record that will be stored within the customer record. A stored address can be used as the billing and/or shipping address on transactions processed for the customer.

Request Method: POST

URL Endpoint: /api/vault/customer/{ customer id }/address

Name	Type	Default	Description
first_name	string	""	Addressee first name
last_name	string	""	Addressee last name
company	string	""	Company name
line_1	string	""	Street address
line_2	string	""	Additional delivery details
city	string	""	City name
state	string	""	State code ("CA")
postal_code	string	""	Postal code ("12345")
country	string	""	Country code ("US")
email	string	""	Email address (must be valid email format, "example@mail.com")
phone	string	""	Phone number ("3216540987")
fax	string	""	Fax number ("3216540987")

Get Address Record By ID

TIP

Address records cannot be fetched individually, please use the Get Customer Record By ID endpoint to retrieve the collection of address records for a specified customer.

Update Address Record

Update an existing address within a customer record.

Request Method: POST

URL Endpoint: /api/vault/customer/{ customer id }/address/{ address id }

Name	Type	Default	Description
first_name	string	""	Addressee first name
last_name	string	""	Addressee last name
company	string	""	Company name
line_1	string	""	Street address
line_2	string	""	Additional delivery details
city	string	""	City name
state	string	""	State code ("CA")
postal_code	string	""	Postal code ("12345")
country	string	""	Country code ("US")
email	string	""	Email address (must be valid email format, "example@mail.com")
phone	string	""	Phone number ("3216540987")
fax	string	""	Fax number ("3216540987")

Delete Address Record

Delete the specified address within a customer record.

Request Method: DELETE

URL Endpoint: /api/vault/customer/{ customer id }/address/{ address id }

json

{
  "status": "success",
  "msg": "success"
}

Create Payment Method Record

Create a new stored payment method on the specified customer record. The url endpoint and request body properties vary depending on the type of payment method being created.

Request Method: POST

Create Card - URL Endpoint: /api/vault/customer/{ customer id }/card

Create ACH - URL Endpoint: /api/vault/customer/{ customer id }/ach

Create Card or ACH with Token - URL Endpoint: /api/vault/customer/{ customer id }/token

Create Card with Apple Pay Token - URL Endpoint: /api/vault/customer/{ customer id }/applepay

Create Card with Google Pay Token - URL Endpoint: /api/vault/customer/{ customer id }/googlepay

Name	Type	Default	Description	Required
number	string	""	Card number
expiration_date	string	""	Card expiration date ("MMYY" or "MM/YY")	*

Create Payment Method Record Code Samples

json

{
  "status": "success",
  "msg": "success",
  "data": {
    "id': '952f250d-fa85-40ac-a45e-3886f98032c6',
    'owner_id': 'testmerchant12345678',
    'data': {
      'customer': {
        'addresses': [
          {
            'city': 'Some Town',
            'company': 'Some Business',
            'country': 'US',
            'email': 'user@somesite.com',
            'fax': '555555555',
            'first_name': 'John',
            'hash': 'cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=',
            'id': 'bl6nqk69ku6897l45fp0',
            'last_name': 'Smith',
            'line_1': '',
            'line_2': '',
            'phone': '5555555555',
            'postal_code': '60187',
            'state': 'IL'
          }
        ],
        'defaults': {
          'billing_address_id': 'bl6nqk69ku6897l45fp0',
          'payment_method_id': 'bl6nqk69ku6897l45fq0',
          'payment_method_type': 'card',
          'shipping_address_id': 'bl6nqk69ku6897l45fp0'
        },
        'description': 'test description',
        'notes': '',
        'flags': ['surcharge_exempt'],
        'payments': {
          'ach': [],
          'cards': [
            {
              'card_type': 'visa',
              'expiration_date': '2020-12-31T00:00:00Z',
              'id': 'bl6nqk69ku6897l45fq0',
              'masked_number': '411111******1111'
            }
          ]
        }
      }
    },
    'created_at': '2019-08-09T09:04:00.786094073-05:00',
    'updated_at': '2019-08-09T09:04:00.786094116-05:00'
  }
}

Get Payment Method Record By ID

TIP

Payment method records cannot be fetched individually, please use the Get Customer Record By ID endpoint to retrieve the collection of payment method records for a specified customer.

Update Payment Method Record

Update an existing payment method within a customer record.

Request Method: POST

Update Card - URL Endpoint: /api/vault/customer/{ customer id }/card/{ payment method id }

Update ACH - URL Endpoint: /api/vault/customer/{ customer id }/ach/{ payment method id }

Update Token - URL Endpoint: /api/vault/customer/{ customer id }/token/{ payment method id }

Name	Type	Default	Description	Required
number	string	""	Card number
expiration_date	string	""	Card expiration date ("MMYY" or "MM/YY")	*
flags	array	[]	"surcharge_exempt", "applepay", "closed_contact", "contact", "locked_security", "locked_stop_recurring"

Update Payment Method Record Code Samples

json

{
  "status": "success",
  "msg": "success",
  "data": {
    "id': '952f250d-fa85-40ac-a45e-3886f98032c6',
    'owner_id': 'testmerchant12345678',
    'data': {
      'customer': {
        'addresses': [
          {
            'city': 'Some Town',
            'company': 'Some Business',
            'country': 'US',
            'email': 'user@somesite.com',
            'fax': '555555555',
            'first_name': 'John',
            'hash': 'cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=',
            'id': 'bl6nqk69ku6897l45fp0',
            'last_name': 'Smith',
            'line_1': '',
            'line_2': '',
            'phone': '5555555555',
            'postal_code': '60187',
            'state': 'IL'
          }
        ],
        'defaults': {
          'billing_address_id': 'bl6nqk69ku6897l45fp0',
          'payment_method_id': 'bl6nqk69ku6897l45fq0',
          'payment_method_type': 'card',
          'shipping_address_id': 'bl6nqk69ku6897l45fp0'
        },
        'description': 'test description',
        'notes': '',
        'flags': ['surcharge_exempt'],
        'payments': {
          'ach': [],
          'cards': [
            {
              'card_type': 'visa',
              'expiration_date': '2020-12-31T00:00:00Z',
              'id': 'bl6nqk69ku6897l45fq0',
              'masked_number': '411111******1111'
            }
          ]
        }
      }
    },
    'created_at': '2019-08-09T09:04:00.786094073-05:00',
    'updated_at': '2019-08-09T09:04:00.786094116-05:00'
  }
}

Delete Payment Method Record

Delete the specified payment method within a customer record.

Request Method: DELETE

Delete Card - URL Endpoint: /api/vault/customer/{ customer id }/card/{ card id }

Delete ACH - URL Endpoint: /api/vault/customer/{ customer id }/ach/{ ach id }

json

{
  "status": "success",
  "msg": "success"
}

Customer Vault ​

Create Customer Record ​

Get Customer Record By ID ​

Search Customer Records ​

Update Customer Record ​

Delete Customer Record ​

Create Address Record ​

Get Address Record By ID ​

Update Address Record ​

Delete Address Record ​

Create Payment Method Record ​

Create Payment Method Record Code Samples ​

Get Payment Method Record By ID ​

Update Payment Method Record ​

Update Payment Method Record Code Samples ​

Delete Payment Method Record ​

Customer Vault

Create Customer Record

Get Customer Record By ID

Search Customer Records

Update Customer Record

Delete Customer Record

Create Address Record

Get Address Record By ID

Update Address Record

Delete Address Record

Create Payment Method Record

Create Payment Method Record Code Samples

Get Payment Method Record By ID

Update Payment Method Record

Update Payment Method Record Code Samples

Delete Payment Method Record