Skip to main content
This guide walks you through the complete Zeam integration flow, from authenticating a user to executing a cross-border payment.

​
Prerequisites

Need credentials? Contact [email protected] to register your application and receive your connect secret.
  • A registered Zeam application with issued credentials
  • Your connect secret (provided during application registration)
  • curl and jq, or the Go SDK

​
Base URL

All API calls use the public gateway: 
https://api.zeam.money/gw

​
Authentication headers

Connect and API calls require your issued connect secret: 
x-zeam-auth: <connect-secret>
Where bearer tokens are also required, include both headers: 
Authorization: Bearer <access-token>
x-zeam-auth: <connect-secret>
1

Request OTP

Request a one-time PIN for user authentication.
curl -s -X POST https://api.zeam.money/gw/v1/public/auth/request-otp \
  -H 'Content-Type: application/json' \
  -d '{
    "zeamid": "user_01HWX...",
    "mobile": "+27821234567",
    "kind": "user"
  }' | jq
The user receives a one-time code via WhatsApp.
2

Verify OTP

Verify the OTP and authenticate the user.
curl -s -X POST https://api.zeam.money/gw/v1/public/auth/verify-otp \
  -H 'Content-Type: application/json' \
  -d '{
    "otp_session_id": "req_01HWX9YZ7T5K8QF3NSDE9B2M0P",
    "otp": "123456"
  }' | jq
Save the returned access_token — this is your bearer token for authenticated calls.
3

Get user businesses

Retrieve the list of businesses available to the authenticated user.
curl -s https://api.zeam.money/gw/v1/business/association/all \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq
Pick the associationId you want to operate with.
4

Get wallets for an association

Retrieve wallets linked to the selected business association.
curl -s https://api.zeam.money/gw/v1/business/wallet/association/$ASSOCIATION_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq
Select the wallet that holds the asset you want to send from.
5

Sign in to Connect

The application uses the public key and secret issued during application registration to authenticate for Connect execution.
curl -s -X POST https://api.zeam.money/gw/v1/public/auth-connect/sign-in \
  -H 'Content-Type: application/json' \
  -d '{
    "publicKey": "'$ZEAM_APP_PUBLIC_KEY'",
    "secret": "'$ZEAM_APP_SECRET'"
  }' | jq
Save the returned idToken — this is your Connect bearer token.
The Go SDK handles this authentication flow automatically. See recipes.ConnectLogin for a one-call solution.
6

Retrieve beneficiaries

Retrieve the beneficiaries linked to the selected business association.
curl -s https://api.zeam.money/gw/v1/business/beneficiaries/$ASSOCIATION_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq
Each beneficiary includes payment destinations (bank accounts, mobile money wallets, etc.).
7

Query available connectors

Use this endpoint to discover which payment connectors are available for a destination country and method.
curl -s -X POST https://api.zeam.money/gw/v1/connect-query \
  -H "Authorization: Bearer $CONNECT_TOKEN" \
  -H "x-zeam-auth: $CONNECT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "countryISO": "ZW",
    "method": "MOMO"
  }' | jq
Supported methods:
MethodDescription
BANKBank transfer
MOMOMobile money
CASHCash pickup
CARDCard payment
WALLETDigital wallet
VOUCHERVoucher / prepaid
QRQR code payment
8

Get a quote

Create a quote for the selected connector and payment route.
curl -s -X POST https://api.zeam.money/gw/v1/connect-quote \
  -H "Authorization: Bearer $CONNECT_TOKEN" \
  -H "x-zeam-auth: $CONNECT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "connectorId": "'$CONNECTOR_ID'",
    "amount": "100.00",
    "currency": "USDC"
  }' | jq
The quote includes the exchange rate, fees, destination amount, and a quoteId for execution.
Quotes are time-limited. Execute promptly — an expired quote will be rejected.
9

Initiate a transaction

Create the transaction intent and receive the transaction reference required for the rest of the flow.
curl -s -X POST https://api.zeam.money/gw/v1/transaction/init \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-zeam-auth: $CONNECT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "'$QUOTE_ID'",
    "associationId": "'$ASSOCIATION_ID'"
  }' | jq
Save the returned transactionId.
10

Load and settle the quote

Load the transaction and settle the quote.
curl -s -X POST https://api.zeam.money/gw/v1/transaction/load \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-zeam-auth: $CONNECT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionId": "'$TRANSACTION_ID'"
  }' | jq
11

Execute the transaction

Execute the transaction after settlement has cleared.
curl -s -X POST https://api.zeam.money/gw/v1/connect-execute \
  -H "Authorization: Bearer $CONNECT_TOKEN" \
  -H "x-zeam-auth: $CONNECT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "'$QUOTE_ID'",
    "transactionId": "'$TRANSACTION_ID'"
  }' | jq
The response includes a transaction ID and status for tracking.

​
Next steps

API concepts

Understand environments, request formats, and error handling.

Authentication

Choose the right auth flow for your integration.

Connect payment flow

Detailed guide for the full cross-border payment lifecycle.

API reference

Complete endpoint reference with interactive playground.