justgold_sdk

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

The wrapper loads the trading UI from JustGold CDN (signed URL from the Partner API). You do not host or deploy the UI yourself.

Documentation: Flutter integration guide · Partner SDK Quickstart

Requirements

  • Flutter 3.10+, Dart 3.0+

Installation

dependencies:
  justgold_sdk: ^1.1.22

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(),
  onAuthRequired: () => refreshSessionFromBackend(),
  onSessionExpired: () => refreshSessionFromBackend(),
  onTokensRefreshed: (payload) => persistTokens(payload),
  onPaymentRequired: (payload, _) {
    Navigator.of(context).push(
      MaterialPageRoute(builder: (_) => PartnerPaymentPage(payload: payload)),
    );
  },
  onError: (error) {
    if (error['fatal'] == true) {
      // SDK cannot load — show your UI or close
    } else {
      debugPrint('SDK error: $error');
    }
  },
  onAnalytics: (event) {
    debugPrint('ANALYTICS ${event['name']} ${event['params']}');
  },
)
Parameter Description
token Required. Session JWT from your backend
refreshToken Enables silent renewal before JWT expiry
sandbox true → sandbox API + CDN; omit or false → production
sdkUiSignedUrl Optional pre-signed CDN URL from your backend (see below)
sdkUrl Optional UI URL override (advanced)
locale 'en' or 'ar'
theme Light/dark mode, brand colors, optional partner branding
onClose User closed the SDK
onAuthRequired Re-issue session — prefer over closing the SDK
onSessionExpired Re-issue session from your backend
onPaymentRequired User confirmed a quote — collect payment on your side
onAnalytics Optional UI taps (ANALYTICS / Invest_*). Also on onSdkEvent
onInvoiceShare Invoice share — fill AcroForm customerName and open your share sheet
onInvoiceDownload Invoice download — fill AcroForm customerName and save or present the PDF
onError { code, message, fatal? } — if fatal, show your UI or close; otherwise log

SDK UI (CDN)

By default, JustGoldConnect calls:

GET /v1/sdk/ui-url?sandbox=true|false
Authorization: Bearer <sessionToken>
→ { "url": "<signed CDN URL>", "expiresAt": "..." }

The signed URL is valid for 1 hour. The wrapper fetches a fresh URL when loading the WebView.

Alternatively, your backend can call the same endpoint and return sdkUiSignedUrl with the session tokens — pass it to JustGoldConnect to skip the in-app fetch.

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) — Completed, Failed, or Cancelled if the user taps Back
  3. Closes your payment screen — the SDK polls: result for complete/fail, or restore buy/sell with the original amount on cancel

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. After Cancelled / Stale the SDK restores the trading form, not pending. 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.

If payment stays Pending for 10 minutes, JustGold marks it Stale. Do not PATCH Stale.

Session recovery (1.1.5+)

When auth fails, the embedded UI runs multi-phase recovery (retries + foreground auto-retry). Implement onAuthRequired to fetch fresh session tokens — do not unmount JustGoldConnect on the first failure. Refresh session again when the app resumes if the SDK is still open.

See CHANGELOG for version history.

Permissions

Your app must declare Android INTERNET in the main manifest (not only the debug manifest):

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET"/>

Without this, release APKs cannot reach the Partner API or CDN. iOS uses standard HTTPS (App Transport Security).

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

Environments

Environment Partner API SDK CDN (signed)
Sandbox https://api.stage.partner.justgold.app https://sdk.stage.justgold.app
Production https://api.partner.justgold.app https://sdk.justgold.app

Set sandbox: true for sandbox integration and testing; false or omit for production. API and CDN hosts are resolved automatically from this flag.

Support

Libraries

justgold_sdk