This reference documents the /v1 REST surface of the Zeam API Gateway. Each
endpoint page is generated from the gateway’s OpenAPI contract and includes an
interactive playground.
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.
Authentication
Every endpoint except POST /auth/token requires three headers:
The x-association-id value is returned as associationId when you issue a
token; a request without it returns 412. See
Authentication for how to obtain and use these.
Conventions
- Requests and responses are JSON with camelCase fields.
- Collections are cursor-paginated.
- Errors use the RFC 7807 problem format; branch on the HTTP
status.
- Every response carries an
X-Request-Id.
Asynchronous payments
The payment endpoints (/payments/p2p, /payments/swap, /payments/offramp)
respond with 202 Accepted: the payment is queued, not settled. The response
carries a transactionRecordId. Track the outcome by polling the transactions
endpoints (see the Transactions group) or by receiving
webhooks. Replaying a submission with the same
idempotencyKey returns the original result with isIdempotent: true.
Endpoint groups
The endpoints are grouped in the sidebar:
- Auth: issue an access token.
- Wallets: list and create wallets (balances embedded), plus wallet-type and network reference data.
- Beneficiaries: manage beneficiaries and their payment destinations.
- Connectors: discover connectors for a corridor.
- Quotes: request an off-ramp quote.
- Payments: send P2P transfers, swaps, and off-ramp cash-outs, and read the off-ramp compliance vocabularies and requirements.
- Transactions: list and read transaction records, the polling complement to webhooks.
- Webhooks: register, list, read, and deactivate webhook registrations.
GET /healthz is an operational readiness probe and is intentionally excluded
from this reference, which covers only the /v1 integrator surface.
