Customers

Returns a paginated list of customer vaults for the authenticated merchant.

Response: { meta: { count, totalPages, page, limit }, data: [...] }.

Query params: page (default 1), limit (default 10; limit=0 returns all), sort (default -updatedAt; prefix with - for descending), keyword (partial match on name, email, phone, company, external id and card last 4), startDay/endDay (filter by creation day; whole days, time component ignored).

Create a new customer vault. Payment methods are provided as a cards array. The first card in the array becomes the default payment method.

Required: firstName, lastName, email.

Optional: companyName, phoneNumber, zipCode, billingAddress, shippingAddress, gender, dateOfBirth, externalId (merchant-side id, e.g. patient MRN), cards. clientId is ignored (derived from your API key).

Card fields: name, number and exp come from the ZeroGateway tokenization callback (response.card.number, masked e.g. 411111******1111; response.card.exp, MMYY), paymentToken (single-use; consumed on success), zipCode. No rate call is needed beforehand: the server classifies the card.

Test mode token: 00000000-000000-000000-000000000000.

Validation: gender is one of Male, Female, Unknown; cards[].number must match ^\d{6}(\d{2})?[*.]+\d{4}$; cards[].exp is 4 digits (MMYY) and must not be in the past; phoneNumber must match the US format ((555) 555-5555 or 5555555555). customValues is accepted for internal use and is not part of the public contract.

Response: paymentMethod is the default method and paymentMethods[] the full list (default entry flagged default: true); address objects also carry email.

Retrieve a single customer vault with all stored payment methods. paymentMethod is the default method; paymentMethods[] lists every stored method with its customerVaultId, last4, exp, network, brand, masked number and default flag.

Soft-delete a customer vault: the record stays retrievable by id with deletedAt set. Stored gateway vaults are removed and the customer subscriptions are cancelled asynchronously. id must be a 24-character hexadecimal ObjectId; other values return 400 Invalid id.

Partial update of a customer vault. Omitted fields keep their current values; null and empty strings are dropped, so a field cannot be cleared through this endpoint.

Cards sent in cards[] are appended as new payment methods and each needs a fresh single-use paymentToken; use the card endpoints to replace or remove a card.

Returns the post-update customer. An unknown id returns 400 (Customer with id: ... not found), not 404.

Soft-delete multiple customer vaults (same semantics as DELETE /customer/{id}). itemList holds customer vault ids (the customer id); at least one is required.

Not atomic: vaults are deleted in parallel and errors are collected, so some may already be deleted when a 400 is returned. Refresh the list after an error.

Hard-delete a stored card from a customer vault. If the deleted card was the default, the first remaining payment method is promoted; paymentMethod is null when none remain.

Note: If the card is referenced by a subscription, deletion is rejected with You cannot delete a Payment Method that is in use and the blocking subscription ids in response.error.entities. All failures are returned as 400. Cancel or reassign the subscription first.

Update an existing stored card in a customer vault. A body customerVaultId is ignored; the path parameter is authoritative.

The returned customerVaultId may differ from the one in the path (the card is re-vaulted at the gateway) and is the authoritative id to use from then on.

type in the response is the card type (credit | debit). billingAddress.country accepts US or CA. Errors (unknown customer or payment method, malformed ids, validation) are returned as 400.

Send a payment-update request link to multiple existing customers at once. Links go to each vault's stored billing email and/or phone; vaults without any contact are skipped.

Body fields: itemList (customer vault ids, i.e. the customer id; at least one), expirationTime (number), unitOfTime (minute(s), hour(s), day(s), week(s)).

success: true means the requests were created and queued, not that they were delivered.

Send a secure link so that a new customer can enter their own payment details. Use this for new customers only — for existing customers use /update-request/:id.

Body fields: expirationTime (required, number), unitOfTime (required: minute(s), hour(s), day(s), week(s)), email (optional), phoneNumber (optional, US number matching ^[+]?[(]?[0-9]{3}[)]?[ ]?[0-9]{3}[-]?[0-9]{4}$, e.g. (555) 555-5555).

At least one of email/phoneNumber must be provided for anything to be sent.

Send a secure link to an existing customer so they can update their payment details. Use when a customer's payment info is incomplete, missing, or needs to be changed.

Body fields: expirationTime (required, number), unitOfTime (required: minute(s), hour(s), day(s), week(s)), email (optional), phoneNumber (optional, US number matching ^[+]?[(]?[0-9]{3}[)]?[ ]?[0-9]{3}[-]?[0-9]{4}$, e.g. (555) 555-5555).

Only the contacts in the body are used (no fallback to the stored customer contacts); at least one of email/phoneNumber must be provided for anything to be sent.

Export all customer vaults of the authenticated merchant as a CSV file (text/csv). Columns, in order: Unique ID, First Name, Last Name, Email Address, Phone Number, Date of Birth, Gender, Company Name, External Identifier, Billing Address Country/City/State/Address 1/Address 2, Shipping Address Country/City/State/Address 1/Address 2, Payment Method, Last 4 Digits, Date (customer last update time, MM/DD/YYYY hh:mm:ss, in the timezone query zone). One column per merchant custom field is appended after Date, so do not hardcode the column count. ZIP codes are not exported. The clientId query param is ignored (derived from your API key).

Download a CSV template for customer import. Warning: if the merchant already has customers, the file contains their live data (one row per customer, Unique ID populated); re-uploading it updates those customers. Columns: the first 19 export columns, then Date (creation time); no Payment Method, Last 4 Digits or custom-field columns. The clientId query param is ignored (derived from your API key).

Upload a CSV file (multipart field file) to bulk-import customers. Columns are read by position, not by header name, and the first row is always skipped as a header. Order: Unique ID, First Name*, Last Name*, Email Address, Phone Number, Date of Birth (MM/DD/YYYY), Gender, Company Name, External Identifier, Billing Country, Billing City, Billing State, Billing Address 1, Billing Address 2, Shipping Country, Shipping City, Shipping State, Shipping Address 1, Shipping Address 2 (* required). A non-empty Unique ID updates that existing customer instead of creating one. The import is synchronous and all-or-nothing: any invalid row rejects the whole file with a 400 listing the failing line numbers.

Add a new stored card (payment method) to an existing customer vault. The first payment method added to an empty vault becomes the default.

Required fields: number (masked, e.g. 411111******1111), paymentToken (from tokenization form, single-use).

Optional: name, exp (MMYY format), zipCode, billingAddress. last4/network are server-derived and any value sent is ignored.

Test mode token: 00000000-000000-000000-000000000000.

zipCode: cardholder billing ZIP; US (12345, 12345-6789) and CA formats are validated.

Mark a stored payment method as the default for this customer vault. Cards and ACH accounts share a single default slot. The method type is not checked: any customerVaultId in paymentMethods[] (card or ACH) is accepted. All failures are returned as 400.

Add an ACH bank account to a customer vault. The first payment method added to an empty vault becomes the default.

Required: accountType, routingNumber, accountNumber, billingAddress (address, city, state, zipCode, country US|CA).

Conditionally required: companyName for business accounts; firstName and lastName for personal accounts; phoneNumber and driverLicenseNumber when the merchant has ACH guarantee enabled.

Unknown fields are rejected. The merchant must have CCD (business) or PPD (personal) enabled for the chosen account type.

Mark a stored payment method as the default for this customer vault. Cards and ACH accounts share a single default slot. The method type is not checked: card and ACH ids are both accepted. All failures are returned as 400.

Replace an existing ACH bank account in a customer vault. This is a full replacement: send the complete payload, including accountNumber, with the same rules as POST ach/:id. The gateway may return a new customerVaultId; use the one in the response from then on.