Skip to main content
​
New: provider on-ramps for bespoke connectors
Connectors
  • Connectors now carry flow: STANDARD (quoted and initiated) or BESPOKE (the customer pays a provider and the payment lands in your wallet). GET /v1/connectors accepts an optional flow filter.
  • Every GET /v1/connectors filter is now optional. Without any, all connectors are listed. Requests that already pass countryIsoCode2, method, and direction are unaffected.
Onramp references
  • New PUT /v1/customers/{customerId}/connectors/{connectorId}/register/individual and .../register/business register a customer with the connector’s provider.
  • New POST, GET and PUT /v1/onramp/references, and PUT /v1/onramp/references/{reference}, register, list and move the references customers pay against. A reference can only be bound to one of your own wallets. See Provider on-ramps.
Webhooks
  • New event types Customer_Verified and Customer_Rejected report a provider’s decision on a customer you registered. See Webhook events.
  • Provider on-ramp payments carry a payout summary in metaData.data (netAmount, totalFees, assetCode, and the reference the payment arrived on).
Documentation corrections (no API change)
  • Webhook events now lists the payment destination decision events, documents source and the per-event metaData, and gives the full Content-Type.
  • The API reference now matches the responses the gateway actually sends: payment destinations carry countryIso, countryName, currencyCode, and region (not countryIsoCode2/currencyIsoCode3); nested beneficiary records, connector providers, and connector limits carry no id; connector transactionTypes[].type is C_2_C/C_2_B/B_2_C/B_2_B; multi-leg transaction records carry legs; wallet balances is null when the balance lookup failed.
  • Missing status codes are documented: 400 for a bad limit or cursor, 404 and 409 on payment submissions, 404 on quotes, and 503/504 on any route that calls a downstream service.
​
Every recorded destination verification state is payable
Payments
  • POST /v1/payments/offramp no longer refuses a destination because of its verificationStatus. Every state (NOT_REQUIRED, PENDING, APPROVED, REJECTED) is payable for either beneficiary classification; the state sets the limits the payment is checked against. This reverses the 2026-09-15 rule that paid a Me beneficiary only through an APPROVED destination.
​
New: on-ramp quotes and collections
Quotes
  • POST /v1/quotes?type=onramp creates an on-ramp quote. amount is what the paying counterparty pays in; the response’s receiveAmount is what lands in your wallet after fee, and total equals sendAmount. Without ?type=onramp the endpoint still creates an off-ramp quote, so existing clients are unaffected.
Payments
  • New POST /v1/payments/onramp: collects from a registered counterparty’s mobile-money payment destination (senderId, paymentDestinationId) into one of your own verified wallets (walletId), executed against an on-ramp quote. Returns 202 Accepted, tracked like any other payment.
​
Beneficiary classification and destination verification
Beneficiaries
  • Beneficiaries now carry a read-only classification (Unverified or Me) and, while Unverified, an unverifiedTier (TIER_0 or TIER_1).
  • Payment destinations now carry verificationStatus and verifyAsMe.
Quotes
  • POST /v1/quotes accepts an optional paymentDestinationId alongside beneficiaryId. Pass it whenever you know the destination; the off-ramp submission requires the same id.
​
Fix: unsupported transaction type returns 422, not 404
Quotes
  • POST /v1/quotes for a connector that exists but does not support the requested transactionType now returns 422 naming the unsupported type, instead of a misleading 404 “connector not found”.
​
Breaking: fromRef/toRef max length reduced from 20 to 16 characters
Payments
  • fromRef and toRef on all payment submissions now allow at most 16 characters (previously 20): ^[A-Za-z0-9-]{1,16}$. A reference of 17-20 characters that was previously accepted now returns a 400 naming the field. Omitted or null still means “no reference”.
​
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.