Conventions

Base URLs, versioning, field formats, and the headers shared by every endpoint.

The gateway uses the same conventions everywhere, so once you learn them they apply to every endpoint.

Base URLs

• Sandbox: https://api.dev.zeam.paytec.io/v1
• Production: https://api.zeam.app/v1

Versioning

The API is versioned in the path (/v1). Additive, backward-compatible changes ship within /v1. Breaking changes ship under a new version. Deprecations are announced ahead of time with Deprecation and Sunset response headers and a changelog entry.

Resource format

• JSON, camelCase. All request and response fields use camelCase.
• Identifiers are UUID strings. Stellar public keys are 56-character G… strings.
• Timestamps are ISO 8601 / RFC 3339 in UTC, for example 2026-01-15T10:30:00Z.
• Amounts are decimal strings where precision matters, to avoid floating-point rounding.

Collections are wrapped for pagination; single resources are returned directly.

Request headers

Header	When	Purpose
Authorization: Bearer	every protected request	Access token. See Authentication.
x-zeam-auth	every protected request	Application secret.
Content-Type: application/json	requests with a body	Required on POST requests.
Idempotency-Key	optional, on writes	Safely retry a mutation without duplicating it, where supported.

Do not send an association id in the URL, body, or a header. The gateway derives it from your token and rejects client-supplied values.

Response headers

Every response includes an X-Request-Id. If you send one, the gateway uses it; otherwise it generates one. Log it and include it in support requests so Zeam can trace the exact call.

Make writes safe to retry: send a unique Idempotency-Key on POST requests so a network retry cannot create a duplicate.