Use the NamiECR SDK to integrate payment functionality into iOS and iPadOS applications. The SDK supports native Swift and Objective‑C, enabling developers to initialize connections, send transaction requests, and process responses with Nami terminals.

For integration steps, refer to iOS ECR Integration.

Prerequisites

• Xcode 14+
• Swift 5.7+ or Objective‑C
• iOS 13.0 or later
• Nami terminal connected to Wi‑Fi
• Valid ECR Reference Number
• Proper app entitlements and permissions configured for networking (App Transport Security in Info.plist)

Library Import

Add the NamiECR SDK framework to your project and import it in your code.

Swift

import NamiECRSDK

Objective‑C

@import NamiECRSDK;

Core Components

• ECRSDK.shared – Singleton for managing connections and transactions
• connectTCP() – Establish direct TCP/IP connection with terminal
• scanDevice() – Discover available terminals automatically
• onSelectDevice() – Select and connect to a discovered terminal
• disconnectTCP() – Disconnect from terminal
• computeSha256Hash() – Generate SHA‑256 signature for requests
• formattedEcrRefNumber() – Generate unique ECR reference number
• doTransaction() – Execute transaction with packed request data
• encryptDecrypt() – Decrypt terminal responses

Permissions (Info.plist Example)

Add the following entries to your Info.plist for network access:

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

Integration Example

Swift

// Connect via TCP/IP
ECRSDK.shared.connectTCP(ip: "192.168.0.102", port: 8888) { status, result in
    DispatchQueue.main.async {
        if status {
            print("Connected successfully")
        } else {
            print("Connection failed: \(String(data: result ?? Data(), encoding: .utf8) ?? "No data")")
        }
    }
}

// Configure CRN and printer
GlobalDataPrefrences.shared.lastCRN = "12345678"
ECRDataManager.shared.enableTerminalPrinter = 1 // Enable printer

// Generate signature and reference number
let uniqueRef = ECRDataManager.shared.formattedEcrRefNumber()
let signature = ECRSDK.shared.computeSha256Hash(uniqueRef + GlobalDataPrefrences.shared.lastConnectedTerminalId!)
let ecrRef = GlobalDataPrefrences.shared.lastCRN! + uniqueRef

// Build request data
let reqData = "\(getFormattedCurrentDate());100;1!;\(ecrRef)!;"
let hexReqData = asciiToHex(reqData)

// Execute transaction
ECRSDK.shared.doTransaction(
    inputReqData: hexReqData as NSString,
    selectedTransactionType: 0, // Purchase
    szSignature: signature as NSString
) { status, response in
    DispatchQueue.main.async {
        if status {
            print("Transaction approved")
        } else {
            print("Transaction failed")
        }
    }
}

Response Parsing Example

Swift

private func handleTransactionResponse(status: Bool, response: Data?, selectedTransactionType: SupportedTransactions) {
    guard status else {
        print("Transaction failed")
        return
    }
    guard let responseData = response,
          let responseHexCryptoString = String(data: responseData, encoding: .utf8) else {
        print("Transaction failed to convert response")
        return
    }
    let plainHexText = ECRCrypto.encryptDecrypt(responseHexCryptoString)
    let decoder = JSONDecoder()
    if let data = plainHexText.data(using: .utf8),
       let transactionResponse = try? decoder.decode(TransactionResponse.self, from: data) {
        print(transactionResponse.responseBody)
    }
}

Error Handling

• Connection failure → Show error toast, enable scan/stop buttons
• Scan failure → Show alert, retry discovery
• Invalid CRN → Must be 8‑digit numeric; reject otherwise
• Timeouts → Retry or prompt user to reconnect
• Missing fields → Validate before processing; abort if null

Security & Signatures

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

Configuration Persistence

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

Runtime Behaviors

• The SDK manages communication through TCP/IP or automatic discovery
• Establish session by connecting directly or scanning for terminals
• Register and start session before initiating transactions
• Build transaction request data (timestamp, amount, CRN, printer flag, reference number)
• Convert request to Hex and execute with doTransaction()
• Responses are returned in encrypted format; decrypt and parse JSON
• Disconnect after transaction completion

Transaction Flow

Initialize SDK → Configure POS → Connect Device (TCP/IP or Scan) → Register (txnType 17) → Start Session (txnType 18) → Execute Transaction → Receive Response → Parse Response → Disconnect