Prerequisites

Install the required environment before using the SDK.

React Native 0.68 or later
Node.js 16 or later
Android Studio (for Android builds)
Xcode (for iOS builds)
Native ECR SDKs (Android/iOS) are bundled inside the React Native wrapper — no DLLs or external native libraries required.

Note: Earlier Java SDK releases required DLL dependencies. React Native SDK is DLL‑free and uses native modules internally.

For integration steps, refer to React Native Integration.

Library Import

Add the React Native ECR SDK dependency and import the classes.

JavaScript / TypeScript

import { PosLibManager, ECRTransactionManager } from 'react-native-ecr-sdk';

Core Components

Use the SDK’s exported modules to build and parse transaction data.

PosLibManager – Initialize SDK, connect/disconnect devices, execute transactions.
ECRTransactionManager – Compute SHA‑256 signatures, generate ECR reference numbers, format requests.
BroadcastReceiver (Android only) – Handles App‑to‑App responses from mada app.
Native Modules – Bridge between React Native JS layer and native Android/iOS SDKs.

Permissions (Manifest Example)

Add the following entries to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
<uses-permission android:name="android.permission.BROADCAST_STICKY"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

Integration Example

JavaScript

// Initialize SDK
PosLibManager.initialize({
  crn: "ECR001",
  terminalIp: "192.168.0.102",
  port: 8888
});

// Build request data
const uniqueNumber = ECRTransactionManager.getSixDigitUniqueNumber();
const signature = ECRTransactionManager.computeSha256Hash(uniqueNumber, "TERMINAL01");
const ecrRef = "ECR001" + ECRTransactionManager.getSixDigitUniqueNumber();

const reqData = `${ECRTransactionManager.getFormattedDateTime()};100;1!;${ecrRef}!;`;
const hexReqData = ECRTransactionManager.stringToHex(reqData);

// Send transaction via TCP/IP
PosLibManager.doTransaction({
  reqData: hexReqData,
  txnType: 0, // Purchase
  signature: signature
});

Response Parsing Example

Responses are returned in JSON or CSV format depending on connection type. Example:

const response = "00,APPROVED,10000,140524193012,TX12345678,RECEIPT123";
const fields = response.split(",");

const responseCode = fields[0];   // 00 = Approved
const approvalCode = fields[1];   // APPROVED
const amount = fields[2];         // 10000 (minor units)
const timestamp = fields[3];      // ddMMyyHHmmss
const ecrRefNo = fields[4];       // Merchant reference
const receiptData = fields[5];    // Receipt payload

Error Handling

mada app not installed → App‑to‑App fails silently; prompt user to install mada app
Timeouts → Retry or fall back to TCP/IP
Invalid CRN → Must be 8‑digit numeric; reject otherwise
Missing fields → Validate before processing; abort if null

Security & Signatures

Always generate a SHA‑256 signature using CRN and terminal ID before sending requests
Validate CRN and transaction reference numbers to prevent replay or tampering
Ensure printer configuration is explicitly set (0 or 1)

Configuration Persistence

Connection parameters (IP, port, Bluetooth device ID, App‑to‑App CRN) are defined at runtime in the client code.
No external JSON configuration file is required.
App‑to‑App requires mada app installed and a broadcast receiver registered to capture responses.

Runtime Behaviors

The SDK manages communication through TCP/IP sockets, Bluetooth pairing, or App‑to‑App intents.
Establish session with the terminal.
Send packed request data using doTransaction().
Receive terminal response and parse with parseResponse().
Close the connection after transaction completion.

Transaction Flow

Initialize SDK → Configure POS → Connect Device → Register (txnType 17) → Start Session (txnType 18) → Execute Transaction → Receive Response → Parse Response