justgold_sdk 1.1.19

JustGold Connect SDK for Flutter — embeddable gold & silver trading UI for partner apps.

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.19

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

• Flutter integration guide
• Partner SDK Quickstart
• Contact your JustGold onboarding team for sandbox credentials and go-live approval