Guides

*New – Android SDK Integration Library

Suggest Edits

The Android SDK enables merchant applications to integrate payment acceptance with Nami terminals. It provides APIs for TCP/IP, Bluetooth, and USB communication, as well as App‑to‑App intent‑based integration with the POS app.

For integration steps, refer to Android SDK Integration.

Prerequisites

  • Android 8.0 (API level 26) or higher
  • Namipay SDK (NamipaySDK-release.aar) added to project
  • Valid Cash Register Number (CRN) (8‑digit numeric)
  • Proper Android permissions configured (network, Bluetooth, USB)
  • POS app with ECR Mode enabled

Library Import

Add the SDK dependency in build.gradle:

repositories {
    flatDir { dirs 'libs/aars' }
}
implementation files('libs/NamipaySDK-release.aar')

Import required classes:

import android.content.Intent;
import android.hardware.usb.UsbDevice;
import android.hardware.usb.UsbDeviceConnection;

Core Components

  • CLibraryLoad.getInstance().getPackData() – Pack transaction request data
  • CLibraryLoad.getInstance().getParseData() – Parse response data
  • ECRSDK.shared.doTransaction() – Execute transaction
  • UsbManager / UsbDeviceConnection – USB OTG communication
  • Intent (App‑to‑App) – Launch POS app and send request packet

Permissions (Manifest Example)

Add required entries to AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<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-feature android:name="android.hardware.usb.host"/>
<intent-filter>
    <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"/>
</intent-filter>

Integration Example

Java – Pack and Send Request via Intent

// Pack request
byte[] packed = CLibraryLoad.getInstance().getPackData(reqData, txnType, szSignature);

// Launch POS app
Intent intent = getPackageManager().getLaunchIntentForPackage("com.skyband.pos.app");
intent.putExtra("message", "ecr-txn-event");
intent.putExtra("request", packed);
intent.putExtra("packageName", "com.Namipay.ecr");
startActivity(intent);

// Handle response
byte[] receivedData = getIntent().getByteArrayExtra("app-to-app-response");
if (receivedData != null && receivedData.length > 0) {
    String receivedIntentData = new String(receivedData).replace("�", ";");
    ActiveTxnData.getInstance().setReceivedIntentData(receivedIntentData);
}

Response Parsing Example

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

String responseCode = fields[0];
String approvalCode = fields[1];
String amount = fields[2];
String timestamp = fields[3];
String ecrRefNo = fields[4];
String receiptData = fields[5];

Error Handling

  • POS app not installed → Intent fails; prompt user to install app
  • Timeouts → Retry or fall back to TCP/IP
  • Invalid CRN → Must be 8‑digit numeric
  • USB permission denied → Request permission via usbManager.requestPermission()
  • Missing fields → Validate before processing

Security & Signatures

  • Always compute SHA‑256 signature using CRN + terminal ID before sending requests
  • Validate CRN and transaction reference numbers to prevent replay/tampering
  • Printer configuration must be explicitly set (0 = disable, 1 = enable)

Configuration Persistence

  • Connection parameters (IP, port, CRN, printer settings) are defined at runtime
  • No external JSON configuration file required
  • CRN and printer preferences stored in GlobalDataPrefrences and ECRDataManager

Runtime Behaviors

  • SDK manages communication via TCP/IP, Bluetooth, USB OTG, or App‑to‑App intents
  • Establish session by sending Register (txnType 17) and Start Session (txnType 18)
  • Build transaction request (timestamp, amount, CRN, printer flag, reference number)
  • Convert request to Hex and execute with doTransaction()
  • Responses returned as byte arrays; parse and display in UI
  • Disconnect after transaction completion

Transaction Flow

Initialize SDK → Configure POS → Connect Device (TCP/IP / Bluetooth / USB / App‑to‑App) → Register (txnType 17) → Start Session (txnType 18) → Execute Transaction → Receive Response → Parse Response → Disconnect

Updated 1 day ago