justgold_sdk

Embed the JustGold gold & silver trading experience in your Flutter app with JustGoldConnect.

The trading UI ships inside this package — no separate UI deploy or CDN.

Documentation: Flutter integration guide · Session tokens · SDK overview

Requirements

  • Flutter 3.10+, Dart 3.0+

Installation

dependencies:
  justgold_sdk: ^1.0.1

flutter pub get

Quick start

Your backend issues a short-lived session JWT (and optional refresh token). Pass them to JustGoldConnect — never put client_secret in the app.

import 'package:flutter/material.dart';
import 'package:justgold_sdk/justgold_sdk.dart';

JustGoldConnect(
  token: sessionToken,
  refreshToken: refreshToken,
  sandbox: false,
  locale: 'en',
  theme: const SdkTheme(
    mode: SdkThemeMode.light,
    primaryColor: '#2563eb',
  ),
  onClose: () => Navigator.of(context).pop(),
  onSessionExpired: () => refreshSessionFromBackend(),
  onTokensRefreshed: (payload) => persistTokens(payload),
  onPaymentRequired: (payload, _) {
    Navigator.of(context).push(
      MaterialPageRoute(builder: (_) => PartnerPaymentPage(payload: payload)),
    );
  },
  onError: (error) => debugPrint('SDK error: $error'),
)
Parameter Description
token Required. Session JWT from your backend
refreshToken Enables silent renewal before JWT expiry
sandbox true → sandbox API; omit or false → production
locale 'en' or 'ar'
theme Light/dark mode, brand colors, optional partner branding
onClose User closed the SDK
onSessionExpired Re-issue session from your backend
onPaymentRequired User confirmed a quote — collect payment on your side
onError Unrecoverable SDK error

Partners do not pass apiBaseUrl — the SDK resolves it from the sandbox flag.

Payment handoff

When the user confirms buy, sell, or delivery, the SDK creates a Pending transaction and calls onPaymentRequired. Your app:

  1. Collects payment (your PSP / wallet)
  2. Updates status via your backend: PATCH /v1/transactions/:id (HMAC)
  3. Closes your payment screen — the SDK polls and shows the result

Recommended: keep JustGoldConnect mounted and present your payment UI on top (modal, overlay, or pushed screen).

If you must unmount JustGoldConnect during payment (for example a native PSP SDK), remount it afterward with the same token and refreshToken. The SDK restores the payment flow automatically — do not re-fetch tokens unless the session expired.

The second argument to onPaymentRequired (resume) is optional and can speed up navigation after payment completes.

Permissions

The SDK does not require camera, location, or other sensitive permissions.

Your app must declare Android INTERNET. iOS uses standard HTTPS (App Transport Security).

Environments

Environment API base
Sandbox https://api.dev.partner.justgold.app
Production https://api.partner.justgold.app

Match the sandbox flag to the environment your backend credentials target.

Support

Libraries

justgold_sdk