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

No /rate call is needed before vaulting: POST /customer and POST /customer/card/{id} classify the card (brand, credit/debit, surcharge eligibility) internally.

---

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. cards is optional — a customer without a card is valid. The first card in cards[] becomes the customer's default payment method.

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 (omit cards or send an empty array) 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"
  }'

---

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.

All /v1/public responses are wrapped in a data envelope.

Customer response
{
  "data": {
    "id": "670fbdf6fce1362341bcaf9f",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "paymentMethod": {
      "customerVaultId": "7581353772",
      "last4": "1111",
      "exp": "1026",
      "network": "visa",
      "brand": "credit",
      "number": "411111******1111",
      "default": true
    },
    "paymentMethods": [
      {
        "customerVaultId": "7581353772",
        "last4": "1111",
        "exp": "1026",
        "network": "visa",
        "brand": "credit",
        "number": "411111******1111",
        "default": true
      }
    ]
  }
}

Field	Description
paymentMethods[]	Every stored card: customerVaultId, last4, exp, network, brand, number (masked), default
paymentMethod	The default payment method (the entry with default: true)

The first card sent on create becomes the default. Cards added later do not replace it — change the default explicitly:

cURL — set default payment method
curl -X PATCH https://api.paywithzero.net/v1/public/customer/card/CUSTOMER_ID/CUSTOMER_VAULT_ID/default \
  -H "Authorization: Basic $(echo -n '[email protected]:yourpassword' | base64)" \
  -H "key-hash: YOUR_KEY_HASH"

The response returns the full customer in data.

---

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. With card.vaultId set, neither card.number nor card.paymentToken is required. The platform charges the customer's default payment method.

To charge a specific non-default payment method, pass "overrideDefaultPaymentMethod": "<paymentMethods[].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"
    },
    "overrideDefaultPaymentMethod": "7581353772",
    "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,
    }),
  }
);

Surcharge on vault charges

The surcharge for a vault charge is computed server-side from the eligibility stored on the payment method. Send the base amount (in cents) and expect the surcharge to be added to the captured total — do not call /rate or add the surcharge yourself.

Vault charge errors

Code	Message	Cause
902	VaultId or PaymentToken is required	card.vaultId and card.paymentToken both missing
906	Customer with id ... not found	The vault does not exist or belongs to another merchant

---

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. The added card does not become the default — use the PATCH .../default endpoint above to change it:

cURL
curl -X POST https://api.paywithzero.net/v1/public/customer/card/CUSTOMER_ID \
  -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=10" \
  -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; limit=0 returns all records and keyword filters by name or email. List responses carry a meta block alongside data:

List response
{
  "meta": { "count": 42, "totalPages": 5, "page": 1, "limit": 10 },
  "data": [ { "id": "670fbdf6fce1362341bcaf9f", "firstName": "Jane", "...": "..." } ]
}

See Pagination & Filtering for details.

---

Next steps

• Tokenization — where paymentToken, masked number and exp come from
• Surcharge Payments — how surcharge applies to token vs. vault charges
• Pagination & Filtering — query large customer lists efficiently
• API Reference → Customers — full endpoint documentation