Skip to main content
The OTP flow authenticates individual users via a one-time code delivered to their mobile phone (WhatsApp by default). Use this when your application needs to sign in a human user rather than a backend service.

​
When to use

Use OTP authentication when:
  • You are building a user-facing application that needs per-user identity
  • Your users have a registered mobile number on the Zeam platform
  • You want Zeam to handle OTP delivery (no need to build your own)

​
How it works

​
Step by step

1

Request the OTP

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"
  }'
Response:
{
  "otp_session_id": "req_01HWX9YZ7T5K8QF3NSDE9B2M0P",
  "masked_destination": "+27•••••4567"
}
The user will receive the code on WhatsApp within seconds.
2

Verify the code

Collect the code from the user and submit it:
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"
  }'
Response:
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "dGhpcyBpcyBh...",
  "expires_at": "2026-05-09T05:52:35Z"
}
3

Use the token

curl -s https://api.zeam.money/gw/v1/business/association/all \
  -H "Authorization: Bearer $ACCESS_TOKEN"

​
Using the Go SDK

import (
    "github.com/ZeamMoney/zeam-sdk-go"
    "github.com/ZeamMoney/zeam-sdk-go/recipes"
)

client, _ := zeam.New(zeam.WithEnvironment(zeam.EnvironmentProduction))

sess, err := recipes.LoginOTP(ctx, client, recipes.LoginOTPInput{
    MobileNumber: "+27821234567",
    AskCode: func(ctx context.Context, hint recipes.OTPHint) (string, error) {
        // Show hint.MaskedDestination to the user, collect the code
        return collectCodeFromUser(), nil
    },
})

​
Endpoints

MethodPathPurpose
POST/v1/public/auth/request-otpSend the OTP, receive a session ID
POST/v1/public/auth/verify-otpExchange the code for tokens
POST/v1/public/auth/refreshRefresh the access token

​
Request fields

FieldRequiredDescription
zeamidYesThe user’s Zeam ID
mobileYesE.164 mobile number (e.g., +27821234567)
kindYesOne of user, member, or third_party_user

​
Error handling

StatusScenarioAction
400Missing or malformed mobileCheck the request body
401Wrong OTP codeAsk the user to re-enter the code
404No matching user for the supplied identifiersVerify the zeamid and mobile
409OTP session already consumedStart a new OTP request
429Too many OTP requestsWait before retrying