Skip to main content
​
Statement lines carry a running balance and a stable row identity
Statements
  • GET /v1/statements/transactions lines now include runningBalance (the wallet’s balance in the asset after the line, matching the PDF statement’s numbers) and rowId (an opaque, stable identity — unique within a wallet’s statement and identical on every export of the same settled row; use it as a dedupe key, e.g. an OFX FITID). Additive — existing clients are unaffected.
​
Breaking: fromRef/toRef are validated (1–20 characters, letters/digits/hyphens)
Payments
  • fromRef and toRef on all payment submissions are now validated: when supplied, a reference must match ^[A-Za-z0-9-]{1,20}$. Anything else — including an explicit empty string — returns a 400 naming the field. Omitted or null still means “no reference”.
  • References are never altered in flight: what you send is exactly what appears on both parties’ statements, and a withdrawal’s toRef is now also printed as the payment reference on the recipient’s bank or mobile-money statement.
​
New: statement lines endpoint — enriched transaction history per wallet and asset
Statements
  • New GET /v1/statements/transactions?walletId&assetCode&startDate&endDate: the wallet’s on-chain statement lines for an asset over a date range — one line per balance movement, with a human description (the payment’s title where it carries one) and the viewing wallet’s own reference for the leg. The same source that renders the Business Portal’s account statement and PDF, so the strings match across surfaces.
​
Breaking: quotes require exactly one of beneficiaryId or transactionType
Quotes
  • POST /v1/quotes now requires exactly one of beneficiaryId or transactionType — never both, never neither. Sending both, or neither, returns a 422 with field-level errors on both fields.
  • beneficiaryId behaves as before: the transaction type is derived server-side from your association and the beneficiary, and the quote is priced for the corridor the payment will actually execute as.
  • transactionType (C2C/C2B/B2C/B2B, case-insensitive) is new: price an exploratory quote directly for a named corridor before choosing a beneficiary. It previously had no effect on the fee and was silently ignored — it’s now validated and honoured with a real, computed price.
​
Optional sender/recipient reference fields on payment submissions
Payments
  • POST /v1/payments/p2p/own, /p2p/beneficiary, /p2p/own/multi, /swap/own, /swap/beneficiary, and /offramp now accept optional fromRef and toRef — free-form references passed through unchanged. Omitted values stay omitted; existing clients are unaffected.
​
Breaking: payment submissions require a single transactionId; gateway-side money-path gates retired
Payments
  • idempotencyKey and externalReference are removed from all payment submission requests (p2p/own, p2p/beneficiary, p2p/own/multi, swap/own, swap/beneficiary, offramp). transactionId is now the only identity field — it doubles as the idempotency key and the reference recorded on the transaction. Replaying the same transactionId still returns the original result with isIdempotent: true.
​
Wallet creation validation: walletName required, nationality/registrationCountry checked against ISO 3166-1
Wallets
  • POST /v1/wallets now rejects a blank walletName.
  • metadata.nationality and metadata.registrationCountry (for third-party FICA wallets) must now be a real ISO 3166-1 country code — alpha-2 or alpha-3, case-insensitive — and are normalised to alpha-3 automatically. A correctly-sized value that isn’t a real country (e.g. XXX) now returns a field error immediately.
​
Third-party wallets: ownAccount and FICA metadata on create
Wallets
  • POST /v1/wallets now accepts ownAccount (boolean, default false) and, when false, a required metadata object carrying the third party’s FICA details (entityType: Person — including sole proprietors — or Business, plus the matching identity or company fields).
  • Wallet resources (create/get/list) now include ownAccount and status (Pending/Verified/Rejected). Only a Verified wallet can transact; own-account wallets are Verified immediately, third-party wallets start Pending until KYC review completes.
​
Webhook signature and timestamp changes
Webhooks
  • The HMAC key for X-Zeam-Signature changed from the association id to the X-Webhook-Id value. Update your signature verification to key on X-Webhook-Id.
  • Deliveries now include X-Webhook-Ts — the delivery timestamp as Unix milliseconds (UTC). Use it to reject stale deliveries and shrink your replay window. See Webhook security.
​
Breaking: payment endpoints, asset model, auth, and connector changes
Breaking changes that require integrator updates.Payments — endpoint split
  • POST /v1/payments/p2p and POST /v1/payments/swap are removed. Use the dedicated variants:
    • POST /v1/payments/p2p/own — same-asset transfer between your own wallets.
    • POST /v1/payments/p2p/beneficiary — same-asset payment to a beneficiary’s CRYPTO destination.
    • POST /v1/payments/swap/own and POST /v1/payments/swap/beneficiary — cross-asset equivalents.
    • POST /v1/payments/p2p/own/multi — new. Sends multiple own-wallet transfers as one atomic Stellar transaction (all legs settle or fail together).
Payments — asset field rename
  • sendingAsset and receivingAsset are renamed to sendingAssetCode and receivingAssetCode across all payment endpoints, including offramp. Supply a bare code (e.g. USDZ); the gateway resolves the issuer server-side.
Assets
  • Added GET /v1/assets and GET /v1/assets/{assetCode} — the platform asset registry, listing each asset’s code and Stellar issuer. Use this to discover valid asset codes before submitting payments.
  • Removed GET /v1/wallet-types and GET /v1/networks. Wallet creation now only accepts walletName and assetCode; network, type, and custody are fixed platform-side.
Authentication
  • The x-association-id header is no longer read or required. The association is resolved server-side from the token’s registered client. Remove it from your requests. A valid token whose client has no registered association now returns 403.
Connectors
  • The country query parameter on GET /v1/connectors is renamed to countryIsoCode2 (ISO 3166-1 alpha-2). Connector responses no longer include a fees array; use POST /v1/quotes for authoritative pricing.
Quotes
  • serviceCommission is removed from the quote response.
Beneficiaries — payment destinations
  • countryIso → countryIsoCode2 (ISO 3166-1 alpha-2); currencyCode → currencyIsoCode3 (ISO 4217) on both input and response.
  • For CRYPTO destinations: supply networkName, assetSymbol, and walletAddress. Internal ids (networkId, assetId, connectorId) are no longer accepted.
Wallets
  • GET /v1/wallets now accepts optional assetCode and networkName filters.
  • Wallet resources now include accountNumber and networkName in place of the internal typeId and networkId fields.
​
Payments, transactions, and webhook management
Reworked the money-movement surface and aligned the documentation with the implemented contract.Payments
  • Added POST /v1/payments/p2p (same-asset transfer), POST /v1/payments/swap (cross-asset transfer), and POST /v1/payments/offramp (cash-out against a quote). Each is asynchronous and returns 202 Accepted with a transactionRecordId; replaying an idempotencyKey returns the original result with isIdempotent: true.
  • Added GET /v1/payments/enums and GET /v1/payments/requirements for the off-ramp compliance vocabularies and per-connector field requirements.
  • Removed the transaction-intent model: POST /v1/intents, GET /v1/intents/{intentId}, and the single POST /v1/payments are no longer part of the integrator surface.
Transactions
  • Added GET /v1/transactions and GET /v1/transactions/{transactionId} to track a submission to its outcome.
Webhooks
  • Added POST /v1/webhooks (register), GET /v1/webhooks/{webhookId} (retrieve), and DELETE /v1/webhooks/{webhookId} (deactivate) alongside listing.
Authentication
  • Protected routes now require the x-association-id header, whose value is returned as associationId when you issue a token.
Documentation
​
Resource expansion: wallets, beneficiaries, connectors
Extended the gateway’s REST surface with read and write operations across wallets, beneficiaries, and connectors.Wallets
  • Added GET /v1/wallets/{walletId} — retrieve a single wallet. Balances are now embedded in the wallet resource (balances array) on List, Get, and Create responses, with best-effort enrichment from Horizon.
  • Added GET /v1/wallet-types — reference list for valid typeId values when creating a wallet.
  • Added GET /v1/networks — reference list for valid networkId values when creating a wallet.
  • POST /v1/wallets now requires assetCode for the initial trustline.
  • Removed GET /v1/wallets/{walletId}/balances and GET /v1/wallets/{walletId}/transactions (use the embedded balances field on the wallet resource instead).
Beneficiaries
  • Added GET /v1/beneficiaries/{beneficiaryId} — retrieve a single beneficiary with full nested detail (individual or business sub-object, addresses, tags, and payment destinations).
  • Added PATCH /v1/beneficiaries/{beneficiaryId} — update a beneficiary using merge semantics.
  • Added GET /v1/beneficiaries/{beneficiaryId}/payment-destinations — list payment destinations for a beneficiary, with optional method filter.
  • Added POST /v1/beneficiaries/{beneficiaryId}/payment-destinations — add a payment destination (BANK, MOBILE_MONEY, or CRYPTO).
  • Added GET /v1/beneficiaries/{beneficiaryId}/payment-destinations/{destinationId} — retrieve a single payment destination.
  • POST /v1/beneficiaries body updated: individual, business, addresses, and tags fields are now accepted. The displayName field has been removed.
Connectors
  • Added GET /v1/connectors/{connectorId} — retrieve a single connector with its full execution steps (not available from the list). Accepts an optional transactionType query parameter to scope step data.
​
Initial documentation
First release of the Zeam API Gateway developer documentation.
  • Overview, API concepts, and quickstart.
  • Authentication: the two-factor model, API keys, and access tokens.
  • Sandbox and production promotion.
  • Webhooks: registration through the business portal and listing via the API.
  • Platform reference: conventions, errors, pagination, and rate limits.
  • API reference generated from the gateway’s OpenAPI contract.
The gateway is in active development. Some operational details (sandbox specifics, production promotion steps, webhook delivery contract, and rate limits) are marked as pending and will be completed as they are confirmed.