The Flutter SDK provides typed clients, authentication lifecycle management, and pre-built recipes for the Zeam API. Pure Dart — works from Flutter (mobile, desktop, web) and from server-side Dart (CLI tools, Cloud Run, server-shelf).
Security boundary: the SDK ships the full gateway surface, but registering an application (POST /v1/application) and handling one-time credentials is server-side only. Mobile Flutter apps should consume the Business/OTP track and /v1/business/* endpoints only.
Install
dart pub add zeam_sdk
# or
flutter pub add zeam_sdk
Create a client
import 'package:zeam_sdk/zeam_sdk.dart';
final client = Client(environment: Environment.production);
Authentication
OTP (user sign-in)
import 'package:zeam_sdk/recipes.dart';
final session = await loginOTP(
client,
LoginOTPInput(
mobileNumber: '+27821234567',
askCode: (hint) async {
return await promptUser('Code sent to ${hint.maskedDestination}');
},
),
);
// session is on TrackBusiness
Ed25519 (backend services)
import 'package:zeam_sdk/recipes.dart';
final session = await connectLogin(
client,
ConnectLoginInput(
stellarSeed: seed, // from your secret manager
publicKey: publicKey,
),
);
// session is on TrackConnect — keypair zeroed after authentication
Making API calls
Typed sub-clients are available via the facade:
// List associations
final associations = await client.business().listAssociations(session);
// Get a wallet
final wallet = await client.business().getWallet(session, walletId);
// Query connectors
final connectors = await client.connect().queryConnectors(
connectSession,
ConnectorQueryInput(countryISO: 'ZA', method: 'BANK'),
);
Recipes
The recipes.dart module provides one-call workflows:
| Recipe | Description |
|---|
loginOTP | Business OTP login |
connectLogin | Full Ed25519 flow (server-side) |
registerApplication | One-time-secret capture (server-side) |
ConnectPayment | 9-step off-ramp payment orchestration (server-side) |
rotateCredential | API key rotation (server-side) |
quoteThenExecute<I, Q, R> | Generic quote-then-execute helper |
| Platform | Support |
|---|
| Android | Supported |
| iOS | Supported |
| macOS | Supported |
| Linux | Supported |
| Windows | Supported |
| Web (Flutter Web) | Supported (uses Fetch via package:http) |
| Dart CLI / server | Supported |
Token persistence
The default token store is in-memory. For Flutter apps, use flutter_secure_storage for persistent storage:
import 'package:zeam_sdk/zeam_sdk.dart';
class SecureTokenStore implements TokenStore {
// Implement load, save, and delete using flutter_secure_storage
}
final client = Client(
environment: Environment.production,
tokenStore: SecureTokenStore(),
);
Error handling
try {
final result = await client.business().listAssociations(session);
} on ZeamError catch (err) {
if (err.kind == ErrorKind.auth) {
// Token expired — re-authenticate
}
if (err.kind == ErrorKind.transient) {
// Retry with backoff
}
print('Error: ${err.code} (request_id=${err.requestId})');
} on WrongTrackException {
// Attempted to use a Business token on a Connect endpoint (or vice versa)
}
Repository
Full source, examples, and detailed documentation:
github.com/ZeamMoney/zeam-sdk-flutter | pub.dev/packages/zeam_sdk 
