Customer Vault

The Customer, or Customer Vault, API allows a merchant to store details about a customer beyond simply storing payment method details. The data is stored on Exact’s secure platform, reducing PCI scope for our Partners, Merchants, and their customers. Customer Vault is an ideal solution for any business that uses an internal customer ID for payment and billing processes, including billing systems, membership services and subscriptions.

A customer can be created through the API with two data elements returned in the response — customer id and customer token.

• Customer id is used to modify, view, and delete details within the customer vault.
• The customer token can be used as a payment token within the Payment APIs.

Payment methods must be added utilizing the customer id obtained after creating the customer. This implementation uses the default payment token associated with the customer vault. The Customer Vault enables secure storage of any relevant data including multiple shipping addresses (with labels) as well as multiple payment methods (only tokens can be linked to the Customer Vault). Shipping addresses can be added at time of creation or any time thereafter.

Create a Customer

In order to create a customer, a request should be submitted to the POST /customer endpoint:

Request: Create Customer

POST /customer
{
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "5551234567",
  "addresses": [
    {
      "label": "Work",
      "city": "Scottsdale",
      "country": "USA",
      "postalCode": "85251",
      "state": "AZ",
      "line1": "7272 Indian School Dr",
      "isDefault": true
    }
  ]
}

Response: Create Customer

{
  "id": "64af8f090674c4d267779e4d",
  "token": "619afa6c-7f24-4c4b-89c6-3d47c4738b5e",
  "createdAt": "2023-07-13T05:28:11.139Z",
  "updatedAt": "2023-07-13T05:28:11.139Z",
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "5551234567",
  "addresses": [
    {
      "label": "Work",
      "city": "Scottsdale",
      "country": "USA",
      "line1": "7272 Indian School Dr",
      "postalCode": "85251",
      "state": "AZ",
      "isDefault": true
    }
  ]
}

As mentioned, the customer id can now be used to manage the customer record.

Linking Payment Methods

The most common use case is to link a payment method to a customer. For details on creating payment methods, please consult our Tokenization section.

As an example, let's assume you have previously created a payment method and have received the token 054f3ce9-ad96-4306-abcc-5722e5313a71 in return. This payment method can be associated with the a customer using the POST /customer/:id/payment-method endpoint.

Request: Link Payment Method to Customer

POST /customer/64af8f090674c4d267779e4d/payment-method
{
  "token": "054f3ce9-ad96-4306-abcc-5722e5313a71",
  "isDefault": true,
  "label": "My Visa Card"
}

Response: Link Payment Method to Customer

{
  "type": "card",
  "token": "37e773f6-218a-475c-ba6e-1bb5330b151e",
  "updatedAt": "2023-07-13T05:44:45.189Z",
  "createdAt": "2023-07-11T23:08:34.291Z",
  "billingDetails": {
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "5551234567",
    "address": {
      "city": "Scottsdale",
      "country": "USA",
      "line1": "7272 E Indian School Rd",
      "postalCode": "85251",
      "state": "AZ"
    }
  },
  "label": "My Visa Card",
  "isDefault": true,
  "card": {
    "brand": "visa",
    "lastFour": "1111",
    "checks": {
      "cvcCheck": "full-match",
      "addressCheck": "not-verified"
    },
    "expiry": {
      "month": 9,
      "year": 2024
    },
    "tokenType": "platform"
  }
}

You can link as many payment methods as you like to a single customer.

When you want to make a payment, you can either use the token value for a specific payment method, or, you can use the customer token value, which will use the default payment method for that customer (isDefault: true)