react-native-sunmi-mtb

Official React Native bridge library for Sunmi POS hardware & Mutual Trust Bank (MTB) / MineSec SoftPOS payment terminals.

Architecture: Pure Headless API (Zero UI)

react-native-sunmi-mtb is a pure headless API bridge. It contains no UI components. Your React Native app builds its own checkout screens. Calling SunmiMtb.saleTransaction("100.00") automatically fires an Android Intent launching the official Bank SoftPOS app (com.mutualtrustbank.msa.stage) for contactless card tapping and PIN entry, returning structured receipt data asynchronously back to your JavaScript code.

⚡ 5-Minute Quick Setup

Step 1: Install Package

npm install react-native-sunmi-mtb
# or
yarn add react-native-sunmi-mtb

Step 2: Add MineSec Maven Credentials in android/build.gradle

Add the MineSec GitHub Maven repository to your root android/build.gradle file under allprojects.repositories:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            name "MineSecMavenClientRegistry"
            url "https://maven.pkg.github.com/theminesec/ms-registry-client"
            credentials {
                username "minesec-product-support"
                password "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"
            }
        }
    }
}

Step 3: Add Android 11+ Package Visibility Queries in AndroidManifest.xml

Declare package visibility in android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required for Android 11+ Inter-App Intent Package Visibility -->
    <queries>
        <package android:name="com.mutualtrustbank.msa.stage" />
        <package android:name="com.mutualtrustbank.msa" />
    </queries>

    <application ...>
        ...
    </application>
</manifest>

💻 Quick Code Usage Example

import React, { useEffect, useState } from 'react';
import { SafeAreaView, Text, TouchableOpacity, Alert, StyleSheet } from 'react-native';
import SunmiMtb, { MsaTransactionResult } from 'react-native-sunmi-mtb';

export const PaymentScreen: React.FC = () => {
  const [isReady, setIsReady] = useState(false);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    const initPos = async () => {
      try {
        // ALWAYS target stage package: com.mutualtrustbank.msa.stage
        await SunmiMtb.init('com.mutualtrustbank.msa.stage');
        const installed = await SunmiMtb.isInstalled();
        setIsReady(installed);
      } catch (err: any) {
        console.error('Init Failed:', err);
      }
    };
    initPos();
  }, []);

  const handlePay = async (amount: string) => {
    if (!isReady) {
      Alert.alert('Error', 'Bank SoftPOS App is not installed on this terminal.');
      return;
    }
    setLoading(true);
    try {
      // Triggers Card Sale Intent
      const result: MsaTransactionResult = await SunmiMtb.saleTransaction(amount);
      Alert.alert(
        'Payment Successful!',
        `Tran ID: ${result.tranId}\nRRN: ${result.rrn}\nAuth Code: ${result.approvalCode}`
      );
    } catch (err: any) {
      Alert.alert('Payment Failed', `${err.code}: ${err.message}`);
    } finally {
      setLoading(false);
    }
  };

  return (
    <SafeAreaView style={styles.container}>
      <Text style={styles.title}>Checkout</Text>
      <TouchableOpacity
        style={[styles.payBtn, loading && styles.disabled]}
        disabled={loading}
        onPress={() => handlePay('100.00')}
      >
        <Text style={styles.btnText}>{loading ? 'Processing...' : 'Pay BDT 100.00'}</Text>
      </TouchableOpacity>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  container: { flex: 1, padding: 20, justifyContent: 'center', backgroundColor: '#0f172a' },
  title: { fontSize: 24, fontWeight: 'bold', color: '#fff', marginBottom: 20, textAlign: 'center' },
  payBtn: { backgroundColor: '#10b981', padding: 16, borderRadius: 12, alignItems: 'center' },
  disabled: { opacity: 0.6 },
  btnText: { color: '#fff', fontSize: 18, fontWeight: 'bold' },
});

📚 API Reference

| Method | Return Type | Description | | :--- | :--- | :--- | | SunmiMtb.init(packageName?: string) | Promise<void> | Initializes bridge targeting com.mutualtrustbank.msa.stage. | | SunmiMtb.isInstalled() | Promise<boolean> | Checks if SoftPOS stage app is installed on the device. | | SunmiMtb.warmUp() | Promise<string> | Pre-warms terminal NFC services. | | SunmiMtb.saleTransaction(amount, posMsgId?) | Promise<MsaTransactionResult> | Launches Card Sale intent with amount string (e.g. "100.00"). | | SunmiMtb.settlement(posMsgId?) | Promise<SettlementResult> | Executes batch settlement intent. | | SunmiMtb.activate(code) | Promise<string> | One-time initial device activation setup. | | SunmiMtb.getDeviceId() | Promise<string> | Fetches native Android device ID (Settings.Secure.ANDROID_ID). |

❓ Frequently Asked Questions (FAQ)

Q1: Do I need to build a custom UI for card tapping or PIN entry?

No, absolutely not. react-native-sunmi-mtb is a headless API library with zero UI. Calling SunmiMtb.saleTransaction("100.00") launches the official Bank SoftPOS application screen. The Bank app handles contactless card tapping, PIN input, EMV processing, and automatically returns the transaction result back to your app.

Q2: Do I need to pass an activation code for every sale transaction?

No. Terminal activation is a one-time device provisioning step done when setting up the Sunmi terminal (either directly inside the Bank SoftPOS UI or once via SunmiMtb.activate(code)). Daily sale transactions only require passing the payment amount and a posMessageId.

Q3: Why does SunmiMtb.isInstalled() return false on Android 11+ devices?

Android 11 (API 30+) introduced strict Package Visibility rules. You must declare <package android:name="com.mutualtrustbank.msa.stage" /> inside the <queries> block of your app's android/app/src/main/AndroidManifest.xml.

Q4: Which package name should I pass to SunmiMtb.init()?

Always pass "com.mutualtrustbank.msa.stage". Do NOT use the Play Store package (com.mutualtrustbank.msa) as it contains a critical intent response bug.

Q5: Why am I getting Gradle build errors about missing com.theminesec.app:poslib?

MineSec hosts their native SDK on a private GitHub Maven repository. Make sure you have added the GitHub Maven repository credentials to allprojects.repositories in your root android/build.gradle file as shown in Step 2.

License

MIT