justgold_sdk 1.0.3

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

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 + 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
onSessionExpired	Re-issue session from your backend
onPaymentRequired	User confirmed a quote — collect payment on your side
onError	Unrecoverable SDK error

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)
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

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