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

​
Base URL

  • https://api.zeam.money/gw/v1
Sandbox and production share this base URL; your application’s registration determines which environment a request runs in.

​
Versioning

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

​
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 JSON numbers, denominated in the asset or currency named alongside them.
Collections are wrapped for pagination; single resources are returned directly.

​
Payment references

Every payment submission accepts two optional references:
  • fromRef — the sender’s reference, shown on the sender’s statement.
  • toRef — the recipient’s reference, shown on the recipient’s statement. On a withdrawal (off-ramp) it is also printed as the payment reference on the recipient’s bank or mobile-money statement.
When supplied, a reference must be 1–16 characters using only letters, digits, and hyphens (^[A-Za-z0-9-]{1,16}$). Anything else — including an explicit empty string — returns a 400 naming the field. Omit the field or send null for no reference. References are never altered in flight: what you send is exactly what appears on statements, so validate the format on your side before submitting.

​
Request headers

The association is resolved server-side from the verified token — you do not need to send an association id header. Payment endpoints take a transactionId in the request body, not a header, so a retry cannot create a duplicate.

​
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.
Payments are safe to retry: replaying the same transactionId returns the original result with isIdempotent: true.