Skip to main content

​
Base URL

All API requests go to a single canonical endpoint: 
https://api.zeam.money/gw
There is no separate sandbox domain. Your access mode (Sandbox mode or full production) is determined by your credentials and account configuration, not by the URL. See Environments for details.
All API calls reach real payment infrastructure. Treat credentials with production-grade care and never commit them to source control.

​
Authentication

Every /v1/* endpoint requires a bearer token in the Authorization header. Connect endpoints additionally require the x-zeam-auth header with your issued connect secret: 
curl -s https://api.zeam.money/gw/v1/business/association/all \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-zeam-auth: $CONNECT_SECRET"
The Zeam API supports three authentication methods, each for a different type of caller:
MethodBest forHow it works
Connect sign-inBackend services, SDKs, CLIsAuthenticate using your issued public key and secret
OTPEnd-user sign-inMobile OTP delivered via WhatsApp
OAuthMobile and web appsOAuth tokens validated at the gateway
All three produce a bearer token that works identically on /v1/* endpoints. See Authentication for full details.

​
Request format

  • Content-Type: application/json for all request bodies
  • Method: Standard HTTP verbs (GET, POST, PUT, DELETE)
  • Path parameters: UUID identifiers in the URL path (e.g., /v1/business/wallet/{id})
  • Query parameters: Filtering and pagination on GET endpoints

​
Response format

Successful responses return JSON. The exact shape depends on the endpoint — see the API reference for each endpoint’s response schema.

​
Errors

Classify errors by HTTP status code. The response body provides additional context but should not be used as the primary branch:
StatusMeaningAction
200Success—
400Validation failedCheck request body or query parameters
401UnauthorizedToken is missing, expired, or invalid — re-authenticate
403ForbiddenToken is valid but lacks permission for this operation
404Not foundResource does not exist or is not visible to your application
409ConflictConcurrent modification or duplicate key
429Rate limitedBack off and retry with exponential delay
5xxServer errorRetry idempotent requests (GET, PUT, DELETE) with backoff
Error responses include a machine-readable code and a human-readable message: 
{
  "ok": false,
  "request_id": "req_01HWX9YZ7T5K8QF3NSDE9B2M0P",
  "error": {
    "code": "VALIDATION",
    "message": "mobile must be in E.164 format"
  }
}
See Errors for full details.

​
Request IDs

Every response includes an X-Request-Id header. This ID correlates the request across the Zeam platform and is essential for debugging:
  • Log it alongside your own request context
  • Surface it in error UIs so users can include it in support tickets
  • Forward it if your service makes downstream Zeam calls within the same request
# The request ID appears in both the header and the response body
curl -si https://api.zeam.money/gw/healthz | grep X-Request-Id
# X-Request-Id: req_01HWX9YZ7T5K8QF3NSDE9B2M0P

​
Versioning

The API uses path-based versioning. All current endpoints are under /v1/*.
  • Additive changes (new endpoints, new optional fields) are non-breaking and land without a version bump
  • Breaking changes are announced in the Changelog with a deprecation period before removal

​
Pagination

List endpoints that return large result sets support cursor-based pagination via query parameters. Check each endpoint’s documentation in the API reference for the specific pagination parameters it supports.

​
Rate limits

Rate limiting is enforced at the gateway level. If you receive a 429 response:
  1. Read the Retry-After header for the recommended wait time
  2. Implement exponential backoff with jitter
  3. Do not retry non-idempotent POST requests without checking the response

​
Security best practices

  • Never embed credentials in client-side code — Stellar seeds, API keys, and connect secrets must stay on your server
  • Use HTTPS exclusively — The production API rejects plain HTTP
  • Rotate credentials regularly — Use the credential rotation endpoints when available
  • Redact sensitive data — Never log tokens, seeds, OTP codes, or API keys
See Security for comprehensive guidance.