halo-sdk-react-native 1.0.0 → 1.0.1

package/README.md

@@ -1,163 +1,731 @@
 # halo-sdk-react-native
 
-React Native plugin for the Halo SDK, enabling Android NFC card-present payment transactions.
+A React Native implementation of the [Halo Dot SDK](https://halo-dot-developer-docs.gitbook.io/halo-dot/sdk/1.-getting-started).
+
+The Halo Dot SDK is an Isolating MPoC SDK payment processing software with Attestation & Monitoring Capabilities. It turns an NFC-capable Android phone into a card-present payment terminal, no extra hardware required.
+
+The diagram below shows the SDK boundary and how it interacts with your app, the cardholder's card, and the Halo payment gateway.
+
+![Halo Dot SDK Architecture](https://static.dev.haloplus.io/static/mpos/readme/assets/full_process_MIPS_1200.png)
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Developer Portal Registration](#developer-portal-registration)
+- [Getting Started](#getting-started)
+  - [Create a React Native App](#create-a-react-native-app)
+  - [Environment Setup](#environment-setup)
+  - [Plugin Installation](#plugin-installation)
+  - [Native Module Setup](#native-module-setup)
+  - [AndroidManifest Permissions](#androidmanifest-permissions)
+  - [JWT — What It Is and How to Set It Up](#jwt--what-it-is-and-how-to-set-it-up)
+    - [JWT Lifetime](#jwt-lifetime)
+    - [JWT Claims](#jwt-claims)
+- [Usage](#usage)
+  - [Step 1 — Request Permissions](#step-1--request-permissions)
+  - [Step 2 — Set Up Callbacks](#step-2--set-up-callbacks)
+  - [Step 3 — Initialize the SDK](#step-3--initialize-the-sdk)
+  - [Step 4 — Run a Transaction](#step-4--run-a-transaction)
+  - [Full Example](#full-example)
+- [API Reference](#api-reference)
+- [Documentation](#documentation)
+- [Testing](#testing)
+- [FAQ](#faq)
+
+---
 
 ## Requirements
 
-- React Native 0.73+
-- Android SDK 29+ (minSdkVersion 29)
-- NFC-capable Android device
+| Requirement | Minimum |
+|---|---|
+| [React Native](https://reactnative.dev/) | 0.73+ |
+| [Java](https://www.java.com/en/) | 21 |
+| Android `minSdkVersion` | 29 |
+| Android `compileSdkVersion` / `targetSdkVersion` | 34+ |
+| Device | NFC-capable Android phone |
+| IDE | [Android Studio](https://developer.android.com/studio/install) recommended |
 
-## Installation
+You will also need:
+- A developer account on the [Halo developer portal](https://go.developerportal.qa.haloplus.io/)
+- A signed Non-Disclosure Agreement (NDA), available on the portal
+- A JWT — generated via the developer portal or your own backend (see [JWT section](#jwt--what-it-is-and-how-to-set-it-up))
 
-### 1. Install the package
+Recommended libraries:
+- [`react-native-permissions`](https://www.npmjs.com/package/react-native-permissions) `^4.0.0` — runtime permission handling
 
-Add the package to your project using npm or yarn:
+> **Note:** Android is the only supported platform.
+
+---
+
+## Developer Portal Registration
+
+You must register on the QA (UAT) environment before going to production.
+
+1. Go to [go.developerportal.qa.haloplus.io](https://go.developerportal.qa.haloplus.io/) and create an account
+2. Verify your account via OTP
+3. Click **Access the SDK**
+   ![access sdk](https://static.dev.haloplus.io/static/mpos/readme/assets/access_sdk.jpg)
+4. Download and accept the NDA
+5. Submit your RSA **public key** and create an **Issuer name** — these are used to verify the JWTs your app will sign
+   ![public key](https://static.dev.haloplus.io/static/mpos/readme/assets/public_key.png)
+6. Copy your **Access Key** and **Secret Key** — you will need these to download the SDK from the Halo Maven repo
+   ![access key](https://static.dev.haloplus.io/static/mpos/readme/assets/access_key.png)
+
+---
+
+## Getting Started
+
+### Create a React Native App
+
+If you don't already have a React Native project, create one:
 
 ```bash
-npm install halo-sdk-react-native
+npx react-native init MyHaloApp --version 0.73.0
+cd MyHaloApp
 ```
 
+### Environment Setup
+
+1. Make sure you have **Java 21** installed. Run `java -version` to check.
+
+2. Open `android/app/build.gradle` and confirm `minSdkVersion` is `29` or higher:
+
+```gradle
+android {
+    defaultConfig {
+        applicationId "com.yourcompany.myapp"
+        minSdkVersion 29       // <-- must be 29+
+        targetSdkVersion 34
+        compileSdkVersion 34
+        // ...
+    }
+}
+```
+
+3. See the [FAQ](#faq) if you have trouble with these SDK version settings.
+
+### Plugin Installation
+
+**1.** Install the npm package:
+
 ```bash
+npm install halo-sdk-react-native
+# or
 yarn add halo-sdk-react-native
 ```
 
-### 2. Configure AWS credentials for the Halo Maven repository
+**2.** Install `react-native-permissions` (recommended for runtime permission handling):
+
+```bash
+npm install react-native-permissions
+```
 
-The plugin fetches the Halo SDK from an S3-backed Maven repo. Provide credentials in `android/local.properties`:
+**3.** The plugin downloads the Halo SDK binaries from an S3-backed Maven repo. Add your credentials (from the [developer portal](#developer-portal-registration)) to `android/local.properties` (create the file if it doesn't exist):
 
 ```properties
 aws.accesskey=YOUR_ACCESS_KEY
 aws.secretkey=YOUR_SECRET_KEY
-aws.token=YOUR_SESSION_TOKEN   # optional
 ```
 
-Or set environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`.
+> **Important:** Never commit `local.properties` to source control. Add it to your `.gitignore`
 
-### 3. Register the native module
+**4.** Add the following snippet to `android/app/build.gradle` so Gradle can read `local.properties` (it may already be there in newer RN templates):
 
-In your `MainApplication`, add `HaloSdkPackage` to `getPackages()`:
-
-```kotlin
-override fun getPackages(): List<ReactPackage> = listOf(
-    MainReactPackage(),
-    HaloSdkPackage(),
-)
+```gradle
+def localProperties = new Properties()
+def localPropertiesFile = rootProject.file('local.properties')
+if (localPropertiesFile.exists()) {
+    localPropertiesFile.withReader('UTF-8') { reader ->
+        localProperties.load(reader)
+    }
+}
 ```
 
-### 4. Extend HaloReactActivity
+### Native Module Setup
 
-In `MainActivity`, extend `HaloReactActivity` instead of `ReactActivity`:
+**5.** Open `android/app/src/main/kotlin/.../MainActivity.kt` and extend `HaloReactActivity` instead of `ReactActivity`:
 
 ```kotlin
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
+import com.facebook.react.defaults.DefaultReactActivityDelegate
 import za.co.synthesis.halo.sdkreactnativeplugin.HaloReactActivity
 
 class MainActivity : HaloReactActivity() {
-    override fun getMainComponentName(): String = "YourAppName"
+
+    override fun getMainComponentName(): String = "MyHaloApp"
+
     override fun createReactActivityDelegate() =
         DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
 }
 ```
 
-This ensures Halo SDK lifecycle management works correctly.
+This replaces `ReactActivity` so that NFC foreground dispatch and the Halo SDK lifecycle are managed automatically.
+
+**6.** Open `android/app/src/main/kotlin/.../MainApplication.kt` and register `HaloSdkPackage`:
+
+```kotlin
+import android.app.Application
+import com.facebook.react.PackageList
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactNativeHost
+import com.facebook.react.ReactPackage
+import com.facebook.react.defaults.DefaultReactNativeHost
+import com.facebook.soloader.SoLoader
+import za.co.synthesis.halo.sdkreactnativeplugin.HaloSdkPackage  // <-- add this import
+
+class MainApplication : Application(), ReactApplication {
+
+    override val reactNativeHost: ReactNativeHost =
+        object : DefaultReactNativeHost(this) {
+            override fun getPackages(): List<ReactPackage> =
+                PackageList(this).packages.apply {
+                    add(HaloSdkPackage())  // <-- add this line
+                }
+
+            override fun getJSMainModuleName(): String = "index"
+            override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG
+            override val isNewArchEnabled: Boolean = false
+            override val isHermesEnabled: Boolean = true
+        }
+
+    override fun onCreate() {
+        super.onCreate()
+        SoLoader.init(this, false)
+    }
+}
+```
+
+### AndroidManifest Permissions
+
+**7.** Add the required permissions to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <uses-feature
+        android:name="android.hardware.camera"
+        android:required="false" />
+
+    <!-- Bluetooth — legacy permissions for API 29/30 -->
+    <uses-permission android:name="android.permission.BLUETOOTH" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+
+    <!-- Bluetooth — API 31+ -->
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
+        android:usesPermissionFlags="neverForLocation" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+
+    <!-- Location (required for Bluetooth LE scanning) -->
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+
+    <!-- Other -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.NFC" />
+
+    <uses-feature android:name="android.hardware.nfc" android:required="true" />
+
+    <application ...>
+        <activity
+            android:name=".MainActivity"
+            ...>
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+
+            <!-- Required: NFC foreground dispatch -->
+            <intent-filter>
+                <action android:name="android.nfc.action.TECH_DISCOVERED" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>
+```
+
+---
+
+## JWT — What It Is and How to Set It Up
+
+Every call to the Halo SDK must include a valid JWT. Think of it as a short-lived, signed pass that proves your app is authorised to accept payments for a given merchant.
+
+The JWT is issued either by the [developer portal](https://go.developerportal.qa.haloplus.io/) (for testing) or by your own backend server (for production). The portal verifies it using the RSA **public key** you submitted during registration.
+
+> **For testing:** use the portal's **Generate Token** tool to get a pre-generated JWT. You do not need to implement signing yourself to get started.
+
+**Recommended approach:** split credentials and JWT retrieval into two files.
+
+**`src/config.ts`** — stores your app's settings (never commit real values to source control):
+
+```typescript
+// Copy this file to config.ts and fill in your values.
+// config.ts should be added to .gitignore.
+export const Config = {
+  // Paste a JWT generated from the developer portal here for testing.
+  // In production, fetch this from your backend instead.
+  tempJwt: 'eyJ...',
+
+  // SDK initialisation options (all obtained from the developer portal)
+  applicationPackageName: 'com.yourcompany.myapp',
+  applicationVersion: '1.0.0',
+  onStartTransactionTimeOut: 300000,  // ms before "tap card" times out
+  enableSchemeAnimations: true,       // show Visa/Mastercard animations
+} as const;
+```
+
+**`src/jwt/JwtToken.ts`** — supplies the JWT when the SDK asks for one:
+
+```typescript
+import { Config } from '../config';
+
+/**
+ * Returns the JWT for the Halo SDK's onRequestJWT callback.
+ *
+ * For testing: set Config.tempJwt to a token from the developer portal.
+ * For production: replace this with a fetch from your backend server.
+ */
+export function getJwt(): string {
+  if (Config.tempJwt) {
+    return Config.tempJwt;
+  }
+  throw new Error(
+    'No JWT configured. Set Config.tempJwt in src/config.ts, ' +
+    'or implement a backend fetch here.',
+  );
+}
+```
+
+> **Note:** `getJwt` is synchronous here for simplicity. If you fetch the JWT from a backend, make it `async` and update the `onRequestJWT` callback accordingly.
+
+### JWT Lifetime
+
+Keep the lifetime short — 15 minutes is the recommended maximum. A stolen JWT can only be abused for as long as it remains valid.
+
+### JWT Claims
+
+| Field | Type | Description |
+|---|---|---|
+| `alg` | String | `RS512` — RSA + SHA-512. Asymmetric signing is required so the server can verify without being able to forge tokens. |
+| `iss` | String | Your issuer name, registered on the developer portal (e.g. `authserver.haloplus.io`). |
+| `sub` | String | Your merchant or application ID. |
+| `aud` | String | The Halo kernel server URL (e.g. `kernelserver.qa.haloplus.io`). |
+| `usr` | String | The signed-in operator/user identifier. |
+| `iat` | NumericDate | UTC timestamp of when the token was created. |
+| `exp` | NumericDate | UTC expiry timestamp. |
+| `aud_fingerprints` | String | CSV of SHA-256 TLS fingerprints for the kernel server. Supports multiple values for certificate rotation. |
+
+---
 
 ## Usage
 
+### Step 1 — Request Permissions
+
+Request the Android runtime permissions before initialising the SDK. Android 12+ (API 31+) uses new Bluetooth permission names.
+
 ```typescript
+// src/permissions.ts
+import { PermissionsAndroid, Platform } from 'react-native';
+
+export async function requestHaloPermissions(): Promise<void> {
+  if (Platform.OS !== 'android') return;
+
+  const sdkVersion =
+    typeof Platform.Version === 'number'
+      ? Platform.Version
+      : parseInt(Platform.Version, 10);
+
+  const permissions: string[] = [
+    PermissionsAndroid.PERMISSIONS.CAMERA,
+    PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
+  ];
+
+  if (sdkVersion >= 31) {
+    // Android 12+ Bluetooth permissions
+    permissions.push(
+      PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
+      PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
+    );
+  }
+
+  await PermissionsAndroid.requestMultiple(permissions);
+}
+```
+
+### Step 2 — Set Up Callbacks
+
+The SDK communicates back to your app through an `IHaloCallbacks` object you provide. Each callback corresponds to a different type of event.
+
+```typescript
+// src/haloCallbacks.ts
 import {
-  HaloSdk,
   type IHaloCallbacks,
+  type HaloAttestationHealthResult,
   type HaloInitializationResult,
   type HaloTransactionResult,
   type HaloUIMessage,
-  type HaloAttestationHealthResult,
 } from 'halo-sdk-react-native';
+import { getJwt } from './jwt/JwtToken';
+
+export function buildCallbacks(options: {
+  onStatusChange: (msg: string) => void;
+  onError: (msg: string) => void;
+  onTransactionResult: (result: HaloTransactionResult) => void;
+}): IHaloCallbacks {
+  return {
+    // Called when the SDK finishes starting up
+    onInitializationResult(result: HaloInitializationResult) {
+      if (result.resultType === 'success') {
+        options.onStatusChange('SDK ready — present a card to pay');
+      } else {
+        options.onError(`Initialisation failed: ${result.errorCode}`);
+      }
+    },
+
+    // Called when a card tap completes (approved, declined, or error)
+    onHaloTransactionResult(result: HaloTransactionResult) {
+      options.onTransactionResult(result);
+    },
+
+    // Called repeatedly during a transaction to tell you what to show the user
+    // e.g. "PRESENT_CARD", "PROCESSING", "APPROVED"
+    onHaloUIMessage(message: HaloUIMessage) {
+      options.onStatusChange(message.msgID);
+    },
+
+    // The SDK asks you for a fresh JWT whenever it needs one
+    onRequestJWT(jwtCallback: (jwt: string) => void) {
+      try {
+        jwtCallback(getJwt());
+      } catch (err: any) {
+        options.onError(`JWT error: ${err.message}`);
+      }
+    },
+
+    // Device failed attestation (tampered OS, emulator, etc.)
+    onAttestationError(details: HaloAttestationHealthResult) {
+      options.onError(`Attestation error: ${details.errorCode}`);
+    },
+
+    // A security check failed (e.g. invalid JWT, revoked merchant)
+    onSecurityError(errorCode: string) {
+      options.onError(`Security error: ${errorCode}`);
+    },
+
+    // The SDK released the camera (e.g. card scheme animation finished)
+    onCameraControlLost() {
+      console.log('Camera released by SDK');
+    },
+  };
+}
+```
+
+### Step 3 — Initialize the SDK
 
-const callbacks: IHaloCallbacks = {
-  onInitializationResult(result: HaloInitializationResult) {
-    console.log('Initialized:', result.resultType);
-  },
-  onHaloTransactionResult(result: HaloTransactionResult) {
-    console.log('Transaction:', result.resultType, result.errorCode);
-  },
-  onHaloUIMessage(message: HaloUIMessage) {
-    console.log('UI Message:', message.msgID);
-  },
-  onAttestationError(details: HaloAttestationHealthResult) {
-    console.error('Attestation error:', details.errorCode);
-  },
-  onRequestJWT(jwtCallback: (jwt: string) => void) {
-    const jwt = getJwtFromYourServer();
-    jwtCallback(jwt);
-  },
-  onSecurityError(errorCode: string) {
-    console.error('Security error:', errorCode);
-  },
-  onCameraControlLost() {
-    console.warn('Camera control lost');
-  },
-};
-
-// Initialize once (e.g. on app start)
-await HaloSdk.initialize(
-  callbacks,
-  'com.your.package.name',
-  '1.0.0',
-  300000, // transaction timeout in ms (optional, default 300000)
-  true,   // enable scheme animations (optional)
-);
-
-// Start a purchase
-const result = await HaloSdk.startTransaction(10.50, 'REF-001', 'ZAR');
-
-// Start a card refund
-const refund = await HaloSdk.cardRefundTransaction(10.50, 'REF-001', 'ZAR');
-
-// Cancel current transaction
+Call `HaloSdk.initialize` once, before running any transactions. A good place is in a `useEffect` when your payment screen mounts.
+
+```typescript
+import { HaloSdk } from 'halo-sdk-react-native';
+import { Config } from './config';
+import { requestHaloPermissions } from './permissions';
+import { buildCallbacks } from './haloCallbacks';
+
+async function setupSdk(
+  onStatusChange: (msg: string) => void,
+  onError: (msg: string) => void,
+  onTransactionResult: (result: any) => void,
+): Promise<void> {
+  // 1. Request permissions first
+  await requestHaloPermissions();
+
+  // 2. Build your callbacks
+  const callbacks = buildCallbacks({ onStatusChange, onError, onTransactionResult });
+
+  // 3. Initialise — the SDK will call onInitializationResult when ready
+  await HaloSdk.initialize(
+    callbacks,
+    Config.applicationPackageName,  // e.g. 'com.yourcompany.myapp'
+    Config.applicationVersion,      // e.g. '1.0.0'
+    Config.onStartTransactionTimeOut, // ms before a tap times out (default 300000)
+    Config.enableSchemeAnimations,    // show Visa/Mastercard animations
+  );
+}
+```
+
+### Step 4 — Run a Transaction
+
+Once the SDK is initialised, you can charge a card:
+
+```typescript
+// Charge R 10.50
+const result = await HaloSdk.startTransaction(10.50, 'ORDER-001', 'ZAR');
+console.log(result.resultType); // e.g. "tap_started"
+
+// Refund R 10.50 to the original card
+const refund = await HaloSdk.cardRefundTransaction(10.50, 'ORDER-001', 'ZAR');
+
+// Cancel a transaction that is waiting for a tap
 await HaloSdk.cancelTransaction();
 ```
 
-## API
+`startTransaction` and `cardRefundTransaction` resolve immediately once the tap is registered — the final payment outcome arrives through `onHaloTransactionResult`.
+
+### Full Example
+
+Below is a minimal but complete payment screen taken directly from the example app in this repo:
+
+```tsx
+// App.tsx
+import React, { useEffect, useState } from 'react';
+import {
+  ActivityIndicator,
+  PermissionsAndroid,
+  Platform,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import {
+  HaloSdk,
+  type HaloTransactionResult,
+  type IHaloCallbacks,
+} from 'halo-sdk-react-native';
+import { getJwt } from './src/jwt/JwtToken';
+import { Config } from './src/config';
+
+export default function App() {
+  const [amount, setAmount] = useState('');
+  const [merchantRef, setMerchantRef] = useState('');
+  const [status, setStatus] = useState('Initialising...');
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    initSdk();
+  }, []);
+
+  async function initSdk() {
+    // Request permissions
+    if (Platform.OS === 'android') {
+      const sdkVersion =
+        typeof Platform.Version === 'number'
+          ? Platform.Version
+          : parseInt(Platform.Version, 10);
+
+      const perms: string[] = [
+        PermissionsAndroid.PERMISSIONS.CAMERA,
+        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
+      ];
+      if (sdkVersion >= 31) {
+        perms.push(
+          PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
+          PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
+        );
+      }
+      await PermissionsAndroid.requestMultiple(perms);
+    }
+
+    const callbacks: IHaloCallbacks = {
+      onInitializationResult(result) {
+        setIsReady(result.resultType === 'success');
+        setStatus(
+          result.resultType === 'success'
+            ? 'Ready — enter amount and tap Charge'
+            : `Init failed: ${result.errorCode}`,
+        );
+      },
+      onHaloTransactionResult(result: HaloTransactionResult) {
+        setStatus(`Result: ${result.resultType} ${result.errorCode}`);
+      },
+      onHaloUIMessage(message) {
+        // The SDK sends messages like "PRESENT_CARD", "PROCESSING", "APPROVED"
+        setStatus(message.msgID);
+      },
+      onRequestJWT(jwtCallback) {
+        try {
+          jwtCallback(getJwt());
+        } catch (e: any) {
+          setStatus(`JWT error: ${e.message}`);
+        }
+      },
+      onAttestationError(details) {
+        setStatus(`Attestation error: ${details.errorCode}`);
+      },
+      onSecurityError(errorCode) {
+        setStatus(`Security error: ${errorCode}`);
+      },
+      onCameraControlLost() {},
+    };
+
+    HaloSdk.initialize(
+      callbacks,
+      Config.applicationPackageName,
+      Config.applicationVersion,
+      Config.onStartTransactionTimeOut,
+      Config.enableSchemeAnimations,
+    ).catch(e => setStatus(`SDK error: ${e.message}`));
+  }
+
+  async function charge() {
+    if (!amount || !merchantRef) {
+      setStatus('Please enter amount and merchant reference');
+      return;
+    }
+    try {
+      const result = await HaloSdk.startTransaction(parseFloat(amount), merchantRef, 'ZAR');
+      setStatus(`Tap accepted: ${result.resultType}`);
+    } catch (e: any) {
+      setStatus(`Error: ${e.message}`);
+    }
+  }
+
+  return (
+    <View style={{ flex: 1, padding: 24, justifyContent: 'center' }}>
+      <Text style={{ fontSize: 13, color: '#555', marginBottom: 16 }}>{status}</Text>
+
+      {!isReady ? (
+        <ActivityIndicator size="large" />
+      ) : (
+        <>
+          <TextInput
+            placeholder="Amount (e.g. 10.50)"
+            value={amount}
+            onChangeText={setAmount}
+            keyboardType="decimal-pad"
+            style={{ borderWidth: 1, borderColor: '#ccc', padding: 8, marginBottom: 8, borderRadius: 4 }}
+          />
+          <TextInput
+            placeholder="Merchant reference (e.g. ORDER-001)"
+            value={merchantRef}
+            onChangeText={setMerchantRef}
+            style={{ borderWidth: 1, borderColor: '#ccc', padding: 8, marginBottom: 16, borderRadius: 4 }}
+          />
+          <TouchableOpacity
+            onPress={charge}
+            style={{ backgroundColor: '#1976D2', padding: 14, borderRadius: 8, alignItems: 'center' }}>
+            <Text style={{ color: '#fff', fontSize: 16, fontWeight: '600' }}>Charge</Text>
+          </TouchableOpacity>
+        </>
+      )}
+    </View>
+  );
+}
+```
+
+---
+
+## API Reference
 
 ### `HaloSdk.initialize(callbacks, packageName, version, timeout?, animations?)`
 
 Initialises the SDK. Must be called before any transaction methods.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `callbacks` | `IHaloCallbacks` | Event handler object |
-| `applicationPackageName` | `string` | Your app's package name |
-| `applicationVersion` | `string` | Your app's version string |
-| `onStartTransactionTimeOut` | `number?` | Tap timeout in ms (default 300000) |
-| `enableSchemeAnimations` | `boolean?` | Show Visa/Mastercard/Amex animations on approval |
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `callbacks` | `IHaloCallbacks` | — | Your callback handler object |
+| `applicationPackageName` | `string` | — | Your app's Android package name |
+| `applicationVersion` | `string` | — | Your app's version string |
+| `onStartTransactionTimeOut` | `number?` | `300000` | Time in ms to wait for a card tap |
+| `enableSchemeAnimations` | `boolean?` | `false` | Show Visa/Mastercard/Amex animations on approval |
 
 ### `HaloSdk.startTransaction(amount, reference, currency)`
 
-Starts a purchase transaction. Resolves with a `HaloStartTransactionResult` once the card tap is accepted or rejected.
+Starts a purchase transaction. Prompts the user to tap their card.
+
+| Parameter | Type | Example |
+|---|---|---|
+| `transactionAmount` | `number` | `10.50` |
+| `merchantTransactionReference` | `string` | `'ORDER-001'` |
+| `transactionCurrency` | `string` | `'ZAR'` |
+
+Returns `Promise<HaloStartTransactionResult>` — resolves when the card tap is registered. The final outcome arrives via `onHaloTransactionResult`.
 
 ### `HaloSdk.cardRefundTransaction(amount, reference, currency)`
 
-Starts a card-present refund transaction.
+Starts a card-present refund. Same parameters as `startTransaction`.
 
 ### `HaloSdk.cancelTransaction()`
 
-Requests cancellation of the current in-progress transaction.
+Cancels the current in-progress transaction (e.g. if the user presses Cancel while waiting for a tap).
 
-## Callbacks (`IHaloCallbacks`)
+### Callbacks (`IHaloCallbacks`)
 
-| Callback                   | Description                                                           |
-|----------------------------|-----------------------------------------------------------------------|
-| `onInitializationResult`   | SDK initialisation complete or failed                                 |
-| `onHaloTransactionResult`  | Final transaction outcome                                             |
-| `onHaloUIMessage`          | Prompt to display to the cardholder (e.g. "Present card")             |
-| `onRequestJWT`             | SDK needs a fresh JWT; call the provided `jwtCallback` with the token |
-| `onAttestationError`       | Device attestation failed                                             |
-| `onSecurityError`          | Security check failed                                                 |
-| `onCameraControlLost`      | SDK released camera control                                           |
+| Callback | When it fires |
+|---|---|
+| `onInitializationResult(result)` | SDK startup complete (success or failure) |
+| `onHaloTransactionResult(result)` | Final payment outcome — approved, declined, or error |
+| `onHaloUIMessage(message)` | Prompt to show the user during a tap: `PRESENT_CARD`, `PROCESSING`, `APPROVED`, etc. |
+| `onRequestJWT(jwtCallback)` | SDK needs a fresh JWT — call `jwtCallback(yourJwtString)` |
+| `onAttestationError(details)` | Device integrity check failed (rooted device, emulator, etc.) |
+| `onSecurityError(errorCode)` | JWT invalid, merchant revoked, or other security failure |
+| `onCameraControlLost()` | SDK has finished using the camera |
 
-## Building the plugin
+---
 
-```bash
-npm install
-npm run build
+## Documentation
+
+Full SDK documentation: [halo-dot-developer-docs.gitbook.io](https://halo-dot-developer-docs.gitbook.io/halo-dot/sdk)
+
+---
+
+## Testing
+
+All transactions are void until your NDA is fully executed.
+
+You can simulate card taps using a virtual NFC card app such as [Visa Mobile CDET](https://apkpure.com/visa-mobile-cdet/com.visa.app.cdet) on a second Android device.
+
+---
+
+## FAQ
+
+**Q: How do I set `compileSdkVersion` / `minSdkVersion` if they're not set or causing issues?**
+
+You can define them in `android/local.properties` and read them in Gradle:
+
+```properties
+sdk.dir=/Users/yourname/Library/Android/sdk
+aws.accesskey=YOUR_ACCESS_KEY
+aws.secretkey=YOUR_SECRET_KEY
+compileSdkVersion=34
+minSdkVersion=29
+```
+
+```gradle
+// android/app/build.gradle
+compileSdkVersion localProperties.getProperty('compileSdkVersion').toInteger()
 ```
+
+---
+
+**Q: The SDK fails to download / Gradle sync fails.**
+
+- Confirm `aws.accesskey` and `aws.secretkey` are in `android/local.properties` with the exact casing shown
+- Open the `android` folder in Android Studio and run **File → Sync Project with Gradle Files**
+- Make sure you accepted the NDA on the developer portal (access is blocked until the NDA is signed)
+
+---
+
+**Q: I get a build error about `HaloReactActivity` or `HaloSdkPackage` not found.**
+
+- Confirm the npm package is installed: `npm install halo-sdk-react-native`
+- Confirm `HaloSdkPackage()` is added in `MainApplication.kt`
+- Confirm `MainActivity` extends `HaloReactActivity` (not `ReactActivity`)
+- Run a Gradle sync in Android Studio
+
+---
+
+**Q: The SDK initialises but transactions never complete.**
+
+- Check that all [AndroidManifest permissions](#androidmanifest-permissions) are declared, especially the NFC `intent-filter` block
+- Check that the NFC intent-filter is inside the `<activity>` block for `MainActivity`
+- Verify your JWT is valid using `POST https://kernelserver.qa.haloplus.io/<sdk-version>/tokens/checkjwt`
+- Check that `minSdkVersion` ≥ 29 and `compileSdkVersion` / `targetSdkVersion` ≥ 34
+
+---
+
+**Q: How do I get a test JWT quickly without implementing RS512 signing?**
+
+Log into the [developer portal](https://go.developerportal.qa.haloplus.io/), navigate to your app, and use the portal's **Generate Token** tool. Paste the result into `Config.tempJwt` in your `config.ts`. Remember to implement proper signing before going to production.

package/android/build.gradle

@@ -21,7 +21,7 @@ rootProject.allprojects {
         ]
 
         flatDir {
-            dirs project(':halo_sdk_react_native_plugin').file('libs')
+            dirs "${project(':halo-sdk-react-native').projectDir}/libs"
         }
 
         repos.each { repo ->

package/android/src/main/kotlin/za/co/synthesis/halo/sdkreactnativeplugin/HaloSdkModule.kt

@@ -24,17 +24,20 @@ class HaloSdkModule(reactContext: ReactApplicationContext) :
 
     @ReactMethod
     fun initializeHaloSDK(args: ReadableMap, promise: Promise) {
-        haloSdkImplementation.initializeHaloSDK(promise, args.toHashMap())
+        @Suppress("UNCHECKED_CAST")
+        haloSdkImplementation.initializeHaloSDK(promise, args.toHashMap() as HashMap<String, Any>)
     }
 
     @ReactMethod
     fun startTransaction(args: ReadableMap, promise: Promise) {
-        haloSdkImplementation.startTransaction(promise, args.toHashMap())
+        @Suppress("UNCHECKED_CAST")
+        haloSdkImplementation.startTransaction(promise, args.toHashMap() as HashMap<String, Any>)
     }
 
     @ReactMethod
     fun cardRefundTransaction(args: ReadableMap, promise: Promise) {
-        haloSdkImplementation.startTransaction(promise, args.toHashMap(), TransactionType.Refund)
+        @Suppress("UNCHECKED_CAST")
+        haloSdkImplementation.startTransaction(promise, args.toHashMap() as HashMap<String, Any>, TransactionType.Refund)
     }
 
     @ReactMethod
@@ -57,7 +60,7 @@ class HaloSdkModule(reactContext: ReactApplicationContext) :
     // Keep UIContext activity reference up to date
     override fun onHostResume() {
         Log.d(TAG, "onHostResume")
-        UIContext.updateActivity(currentActivity)
+        UIContext.updateActivity(reactApplicationContext.currentActivity)
     }
 
     override fun onHostPause() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halo-sdk-react-native",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "React Native plugin for Halo SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",