Quickstart

Issue an access token and make your first authenticated call against the sandbox.

This walks you from credentials to a working request in three steps. Sandbox and production share one base URL; your application’s registration determines the environment.

Base URL: https://api.zeam.money/gw/v1

Sandbox and production use the same base URL. Your application’s registration determines which environment a request runs in.

A sandbox token does not provide test isolation from production: records you create and funds you move are real either way. See Sandbox limitations before you go further.

1. Get sandbox credentials

   Register an application in the business portal (or ask an administrator to) to get its clientId, client secret, and application secret (apiKey). See API keys.

2. Issue an access token

   Exchange your client credentials for a short-lived bearer token. No bearer token is needed for this call — you don’t have one yet — but every request, including this one, still needs your application secret as x-zeam-auth.

   cURL

   curl -sS https://api.zeam.money/gw/v1/auth/token \
     -H "Content-Type: application/json" \
     -H "x-zeam-auth: $ZEAM_APP_SECRET" \
     -d '{
       "clientId": "11111111-1111-1111-1111-111111111111",
       "clientSecret": "$ZEAM_CLIENT_SECRET"
     }'
   

   The response contains the token and its lifetime in seconds:

   Response

   {
     "accessToken": "eyJ0eXAiOiJKV1Qi...",
     "tokenType": "Bearer",
     "expiresIn": 3599,
     "associationId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
   }
   

   The associationId is informational — the gateway resolves your association server-side from the bearer token, so there’s nothing to keep or send.

3. Call a protected endpoint

   Every protected request carries two headers: the bearer token and your application secret as x-zeam-auth.

   cURL

   curl -sS https://api.zeam.money/gw/v1/wallets \
     -H "Authorization: Bearer $ZEAM_TOKEN" \
     -H "x-zeam-auth: $ZEAM_APP_SECRET"
   

   A successful response is a paginated collection:

   Response

   {
     "data": [
       { "id": "…", "walletName": "Treasury ZAR", "publicKey": "G…" }
     ],
     "pagination": { "nextCursor": null, "hasMore": false }
   }
   

Next steps

Authentication

Understand tokens, the application secret, and association scoping.

Your first transaction

Go from credentials to a completed P2P transfer with status tracking.

API reference

Browse every endpoint and try requests in the playground.

Errors

Learn the RFC 7807 error format and how to handle failures.