Customer Vault

Store customers, their addresses, and their payment methods. Reuse them on transactions, recurring subscriptions, and invoices.

Canonical endpoints

This page documents the current, canonical endpoints under /api/vault/.... A legacy “Customers” set of endpoints still works, but mixing the two in the same integration can produce unexpected results — pick one and stick with it.

CVV is never stored

To stay PCI-compliant, the gateway does not store card verification values (CVV/CVC). For context, see the PCI Security Standards Council FAQ.

Customers

Create customer

POST /api/vault/customer

Field	Type	Description
`id`	string	Optional custom ID. Max 40 characters, `a-z A-Z 0-9`. Omit to let the gateway generate one.
`id_format`	string	Optional format instruction like `xid_type_last4` for auto-generated IDs. Mutually exclusive with a custom `id`.
`description`	string	Free-text, max 255 characters.
`flags`	string array	Customer-level flags, e.g. `["surcharge_exempt"]`.
`default_payment`	object	Starter payment method. Exactly one of `card`, `ach`, `token`, `apple_pay`, or `google_pay_token`.
`default_payment.card`	object	`number` and `expiration_date` (`MMYY` or `MM/YY`).
`default_payment.ach`	object	`account_number`, `routing_number`, `account_type` (`checking`/`savings`), `sec_code` (`web`/`ccd`/`ppd`).
`default_payment.token`	string	Tokenizer token.
`default_payment.apple_pay`	object	`key_id`, `processor_id`, and either `temporary_token` (from WalletJS) or `pkpaymenttoken` (from Apple Pay JS).
`default_payment.google_pay_token`	object/string	Google Pay token payload or the JSON string.
`default_billing_address`	object	First/last name, company, `line_1`, `line_2`, city, state, postal_code, country, email, phone, fax.
`default_shipping_address`	object	Same shape as `default_billing_address`.

Get customer by ID

GET /api/vault/{customer_id}

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

Search customers

POST /api/vault/customer/search

Filter by any of the fields below using the {operator, value} shape (= or !=), or date ranges using {start_date, end_date}.

Field	Notes
`id`, `address_id`, `billing_address_id`, `shipping_address_id`	ID-based filters.
`first_name`, `last_name`, `company`, `email`, `phone`, `fax`	Person/contact filters.
`address_line_1`, `address_line_2`, `city`, `state`, `postal_code`, `country`	Address filters.
`payment_method_type`	`card` or `ach`.
`created_at`, `updated_at`	Date-range filters.
`limit` / `offset`	Defaults `10` / `0`. Max 100 / 1000.

Update customer

POST /api/vault/customer/{customer_id}

Field	Description
`description`	Max 255 characters.
`notes`	Max 255 characters.
`flags`	E.g. `["surcharge_exempt"]`.
`defaults.billing_address_id`	Address ID to use as the billing default.
`defaults.shipping_address_id`	Address ID to use as the shipping default.
`defaults.payment_method_id`	Required if `payment_method_type` is set.
`defaults.payment_method_type`	`card` or `ach`. Required if `payment_method_id` is set.

Delete customer

DELETE /api/vault/{customer_id}

Addresses

Addresses are nested under a customer record. They cannot be fetched individually — use Get customer by ID to retrieve them.

Create address

POST /api/vault/customer/{customer_id}/address

Body accepts the standard address fields: first_name, last_name, company, line_1, line_2, city, state, postal_code, country, email, phone, fax.

Update address

POST /api/vault/customer/{customer_id}/address/{address_id}

Delete address

DELETE /api/vault/customer/{customer_id}/address/{address_id}

Payment methods

Like addresses, payment methods live under a customer and cannot be fetched individually — use Get customer by ID to list them. The URL differs depending on what kind of payment method you are creating.

Create payment method

Method	Endpoint
Card	`POST /api/vault/customer/{customer_id}/card`
ACH	`POST /api/vault/customer/{customer_id}/ach`
Tokenizer token	`POST /api/vault/customer/{customer_id}/token`
Apple Pay	`POST /api/vault/customer/{customer_id}/applepay`
Google Pay	`POST /api/vault/customer/{customer_id}/googlepay`

Card and ACH request bodies use the same shape as the default_payment sub-objects on customer create. The token endpoint takes a token string from Tokenizer. Apple Pay / Google Pay take the wallet payloads described in WalletJS.

Update payment method

Method	Endpoint
Card	`POST /api/vault/customer/{customer_id}/card/{payment_method_id}`
ACH	`POST /api/vault/customer/{customer_id}/ach/{payment_method_id}`
Token	`POST /api/vault/customer/{customer_id}/token/{payment_method_id}`

Beyond the usual fields, you can set flags: surcharge_exempt, applepay, closed_contact, contact, locked_security, locked_stop_recurring.

Delete payment method

Method	Endpoint
Card	`DELETE /api/vault/customer/{customer_id}/card/{card_id}`
ACH	`DELETE /api/vault/customer/{customer_id}/ach/{ach_id}`