API Conventions & Errors

This page covers the things that work the same way across every Zentact API endpoint. Reading it once will make the individual endpoint pages easier to follow.

Base URLs and environments

Zentact has two separate environments, each with its own base URL and its own API keys. See Getting started for more.

Every path in this reference is added to the base URL. For example, GET /api/v1/organizations becomes https://test.api.zentact.com/api/v1/organizations in test.

Authentication

Every request needs your API key in the X-API-Key header. Keys are created in the admin portal and only work in the environment they were created in.

curl https://test.api.zentact.com/api/v1/organizations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

If the key is missing, invalid, or deactivated, the request is rejected with HTTP 401 and an empty body.

Response format

Every response has the same shape, with a status field at the top.

A successful response returns HTTP 200, a status of "ok", and the result in data:

{
  "status": "ok",
  "data": {}
}

A failed response returns an error status, a status of "error", an errorCode, and usually an errorMessage describing what went wrong:

{
  "status": "error",
  "errorCode": "MERCHANT_ACCOUNT_NOT_FOUND",
  "errorMessage": "Merchant account with id MERXXXXXXXXXX not found"
}

Validation errors return a validationErrors list instead of an errorMessage. See below.

HTTP status codes

Validation errors

When the request data does not match what an endpoint expects, you get a 422 with an errorCode of SCHEMA_VALIDATION_ERROR. The validationErrors list has one entry per field that failed, and each path points to the field:

{
  "status": "error",
  "errorCode": "SCHEMA_VALIDATION_ERROR",
  "validationErrors": [
    {
      "code": "custom",
      "message": "Invalid phone number format. Please ensure your phone number follows the E.164 format (e.g., +12345678900).",
      "path": ["businessPhoneNumber"]
    }
  ]
}

Each endpoint page lists the error codes specific to it (for example, the Merchant Accounts API).

Amounts

All amounts are whole numbers in the currency's smallest unit. For example, $12.99 USD is 1299 and €5.00 EUR is 500. Currencies use their ISO 4217 code (USD, EUR, and so on).

The one exception is GET /api/v1/transactions/:pspReferenceId, which returns amounts as decimals in the main currency unit (for example, 12.99).

Dates

Endpoints use one of two date formats:

• Calendar dates like 2025-11-30, used by list filters such as startDate and endDate on the Transactions API.
• Full timestamps like 2025-11-30T23:59:59Z, used by fromDate and toDate on the Reports API.

Timestamps in responses (such as createdAt) are in UTC. A few report fields use plain calendar dates instead, like date in payment volume rows. Webhook createdAt values are a Unix timestamp in seconds.

Pagination

Zentact uses two ways to page through lists.

Page numbers (most list endpoints)

Pass pageIndex (starting at 0) and pageSize. pageSize usually defaults to 50, and the maximum depends on the endpoint. The response includes a pagination object next to the rows:

{
  "status": "ok",
  "data": {
    "pagination": {
      "pageIndex": 0,
      "pageSize": 50,
      "pageCount": 3,
      "total": 120,
      "hasPrevPage": false,
      "hasNextPage": true
    },
    "rows": []
  }
}

Cursors (GET /api/v2/transactions)

For very large lists, the v2 Transactions endpoint uses a cursor. Request the first page without a cursor, then pass the nextCursor from each response as the cursor on the next request, and keep going while hasMore is true. Cursor responses do not include a total count.

Reference IDs

Most create endpoints let you pass your own referenceId (or merchantReferenceId). Zentact saves it and sends it back in API responses and in the matching webhooks, so you can match Zentact records to records in your own system. Use a value that is unique in your system.