Use the NamiPay API Middleware to integrate payment acceptance into Windows‑based POS applications via REST calls.
This guide provides step‑by‑step instructions for:

• Configuration management
• Transaction execution
• Response handling

For environment setup and middleware details, refer to API Middleware Library.

Supported Connections

Transaction Flow

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

Integration Steps

Note: Always ensure the middleware service (nami-ecr-middleware.exe) is running before sending any API call.

Step 1: Start Middleware

• Launch nami-ecr-middleware.exe on Windows.
• Confirm port 9099 is available.
• Verify terminal is connected via LAN or COM.

Step 2: Configure POS Application

• Enable ECR Mode in the POS application.
• Define Cash Register Number (CRN) and cashier setup.
• Ensure POS can reach middleware on localhost:9099.

Step 3: Build Transaction Request

JSON Payload Example (TCP/IP):

{
  "paymentRequest": {
    "date": "130623193000",
    "ecrReferenceNo": "12345678000002",
    "amount": "002",
    "txnType": "0"
  },
  "tcpipcomData": {
    "ip": "192.168.0.102",
    "port": "8888"
  }
}

Step 4: Send HTTP Request

POST Request Example:

POST http://localhost:9099/performTransactionTCPIP
Content-Type: application/json

Payload: JSON request (as above).

For COM integration, use /performTransactionCOM.

Step 5: Handle Response

Responses are returned in JSON format.
They contain:

• Response Code
• Approval Code
• Receipt Data
• Transaction Metadata (RRN, Auth Code, TID, MID, Batch No, Scheme Label, Merchant Info, Signature)

Example Response:

{
  "responseCode": "00",
  "approvalCode": "APPROVED",
  "receiptData": "RECEIPT123",
  "rrn": "TX12345678",
  "timestamp": "140524193012"
}

Step 6: Disconnect

• Call /tcp-ip/disconnect or /com/disconnect after transaction completion.
• Use /getExistingConnections or /get-com-ports to verify active connections.

Step 7: Error Handling

• Connection failure → Verify IP/Port or COM availability
• Invalid CRN → Must be 8‑digit numeric
• Timeouts → Retry or abort gracefully
• Middleware not running → Ensure .exe service is started
• Missing fields → Validate before parsing

Step 8: Security & Signatures

• Always compute SHA‑256 signature using CRN + terminal ID before sending requests
• Validate CRN and transaction reference numbers to prevent replay/tampering
• Ensure middleware port is secured (firewall rules, local access only)

Step 9: Process Response

• Responses are JSON, not CSV (unlike SDKs).
• Parse JSON fields directly in your POS application:

// Example in Dart
final response = {
  "responseCode": "00",
  "approvalCode": "APPROVED",
  "amount": "10000",
  "timestamp": "140524193012",
  "ecrRefNo": "TX12345678",
  "receiptData": "RECEIPT123"
};

print("Response Code: ${response['responseCode']}");
print("Approval Code: ${response['approvalCode']}");
print("Amount: ${response['amount']}");
print("Timestamp: ${response['timestamp']}");
print("ECR Ref No: ${response['ecrRefNo']}");
print("Receipt Data: ${response['receiptData']}");

Key Rules

• Always start middleware before sending requests.
• TCP/IP is the preferred priority connection.
• COM is fallback mode.
• Transaction type 0 represents the end‑to‑end purchase flow.
• Other transaction types (Refund, Reversal, Reconciliation, etc.) are supported via the same REST endpoints.
• For App‑to‑App flows, use SDKs (not middleware).

Final Integration Flow

Start Middleware
↓
Set Configuration (application.properties)
↓
Test Connection (/tcp-ip/connect or /com/connect)
↓
Select Device Priority (TCP/IP → COM)
↓
Execute Transaction (/performTransactionTCPIP or /performTransactionCOM)
↓
Receive Response (JSON payload)
↓
Parse Response (map JSON fields)

Installation Notes

• Requires Windows 10+.
• Requires JRE 8+.
• Middleware runs as a local .exe service.
• Cashier setup (CRN, printer configuration) must be completed at first launch.
• Port 9099 must be available and not blocked by firewall.