Documentation

Copy page

Customer Vault

The customer vault lets you store a customer's payment information — cards and bank accounts — so they don't have to re-enter their details on every transaction. Instead of collecting and tokenizing a new card each time, you charge by referencing a stored vault entry.

---

How vault storage works

1. Collect a card using ZeroGateway.js to get a single-use paymentToken
2. Create a customer (or add a card to an existing one), passing the paymentToken
3. Store the customer id returned in the response — this is your permanent vault reference
4. Charge future transactions using card.vaultId set to that customer id

---

Create a customer with a card

Pass the paymentToken from tokenization in the cards array. The card is vaulted and the token is consumed in the same request.

cURL
curl -X POST https://api.paywithzero.net/v1/public/customer \
  -H "Authorization: Basic $(echo -n '[email protected]:yourpassword' | base64)" \
  -H "key-hash: YOUR_KEY_HASH" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "phoneNumber": "5551234567",
    "zipcode": "95101",
    "cards": [
      {
        "name": "Jane Smith",
        "number": "411111******1111",
        "exp": "1026",
        "paymentToken": "PAYMENT_TOKEN_FROM_COLLECTJS",
        "zipCode": "95101"
      }
    ],
    "billingAddress": {
      "address": "123 Main St",
      "city": "San Jose",
      "state": "CA",
      "zipCode": "95101",
      "country": "US"
    }
  }'

---

Create a customer without a card

You can create a customer record first and add cards later:

cURL
curl -X POST https://api.paywithzero.net/v1/public/customer \
  -H "Authorization: Basic $(echo -n '[email protected]:yourpassword' | base64)" \
  -H "key-hash: YOUR_KEY_HASH" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "phoneNumber": "5551234567",
    "zipcode": "95101",
    "cards": []
  }'

---

Retrieve a customer

cURL
curl https://api.paywithzero.net/v1/public/customer/CUSTOMER_ID \
  -H "Authorization: Basic $(echo -n '[email protected]:yourpassword' | base64)" \
  -H "key-hash: YOUR_KEY_HASH"

The response contains two different identifier fields. Understanding the difference between them is critical for charging correctly.

Customer response
{
  "id": "670fbdf6fce1362341bcaf9f",
  "firstName": "Jane",
  "lastName": "Smith",
  "paymentMethod": {
    "customerVaultId": "7581353772"
  },
  "paymentMethods": [
    {
      "customerVaultId": "7581353772"
    }
  ]
}

---

Critical: id vs customerVaultId

• id (670fbdf6fce1362341bcaf9f) — use as card.vaultId in charge requests
• paymentMethod.customerVaultId (7581353772) — internal reference only, DO NOT use as card.vaultId

---

Charge a stored card via vaultId

Use card.vaultId with the customer's id to charge without re-collecting card details. The platform will use the 'default' payment method for that customer.

If you need to use a specific non-default payment method in that Customer, use the parameter "overrideDefaultPaymentMethod": "<paymentMethod.customerVaultId>":

cURL
curl -X POST https://api.paywithzero.net/v1/public/payment/charge \
  -H "Authorization: Basic $(echo -n '[email protected]:yourpassword' | base64)" \
  -H "key-hash: YOUR_KEY_HASH" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "card": {
      "vaultId": "670fbdf6fce1362341bcaf9f"
    },
    "contact": {
      "email": "[email protected]",
      "phone": "5551234567"
    },
    "billingAddress": {
      "address": "123 Main St",
      "city": "San Jose",
      "state": "CA",
      "zipCode": "95101",
      "country": "US"
    },
    "order": {
      "amount": 1000,
      "shipping": 0,
      "tax": 0,
      "discount": 0
    },
    "capture": true,
    "sendReceipt": false
  }'

JavaScript
const response = await fetch(
  "https://api.paywithzero.net/v1/public/payment/charge",
  {
    method: "POST",
    headers: {
      Authorization: `Basic ${btoa("[email protected]:yourpassword")}`,
      "key-hash": "YOUR_KEY_HASH",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 1000,
      card: { vaultId: "670fbdf6fce1362341bcaf9f" },
      contact: { email: "[email protected]" },
      billingAddress: {
        address: "123 Main St",
        city: "San Jose",
        state: "CA",
        zipCode: "95101",
        country: "US",
      },
      order: { amount: 1000, shipping: 0, tax: 0, discount: 0 },
      capture: true,
    }),
  }
);

---

Add a card to an existing customer

To add a new payment method to an existing customer, POST a card object to the customer's card endpoint. Collect a fresh paymentToken first:

cURL
curl -X POST https://api.paywithzero.net/v1/public/customer/CUSTOMER_ID/card \
  -H "Authorization: Basic $(echo -n '[email protected]:yourpassword' | base64)" \
  -H "key-hash: YOUR_KEY_HASH" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "number": "411111******1111",
    "exp": "1026",
    "paymentToken": "PAYMENT_TOKEN_FROM_TOKENIZATION",
    "zipCode": "95101"
  }'

---

List customers

cURL
curl "https://api.paywithzero.net/v1/public/customer?page=1&limit=20" \
  -H "Authorization: Basic $(echo -n '[email protected]:yourpassword' | base64)" \
  -H "key-hash: YOUR_KEY_HASH"

The default limit is 10. Use page and limit to paginate. See Pagination & Filtering for details.

---

Next steps

• Pagination & Filtering — query large customer lists efficiently
• Subscriptions — use vault customers in recurring billing plans
• API Reference → Customers — full endpoint documentation