Use the Nami ECR .NET SDK to integrate payment acceptance into Windows-based POS applications and billing systems.

This guide provides step-by-step instructions for:

• TCP/IP communication
• Serial (COM) communication
• Terminal registration
• Session management
• Payment execution
• Response handling

For environment setup and SDK details, refer to the .NET SDK Library .

Supported Connections

Transaction Flow

For both TCP/IP and Serial (COM) communication, the transaction flow remains the same.

Connect → Register Terminal (17) → Start Session (18) → Purchase (0) → Disconnect

Note: Execute transactions in the specified order. Skipping registration or session initialization can cause transaction failures.

Integration Steps

Step 1: Establish TCP/IP Connection

Connect the Merchant Application to the Nami Payment Terminal using the terminal IP address and port number.

Use the following code to connect to the terminal:

string ipAddress = "192.168.2.23";
int port = 16535;

int connectResult = ecr.doTCPIPConnection(ipAddress, port);

if (connectResult != 0)
{
    Console.WriteLine("Connection failed with code " + connectResult);
    return;
}

Console.WriteLine("Connected successfully over TCP/IP.");

Developer Note: Place this after SDK initialization. Handle errors such as wrong IP, network issues, or firewall blocks.

Step 2: Register the Terminal

Register the terminal using transaction type 17.

Use the following code to register the terminal:

string timestamp = DateTime.Now.ToString("ddMMyyHHmmss");
string terminalId = "12345678";

string registerData = $"{timestamp};{terminalId}!";

string registerResponse;

int registerResult = ecr.doTCPIPTransaction(
    ipAddress,
    port,
    registerData,
    17,
    "",
    out registerResponse
);

if (registerResult != 0)
{
    Console.WriteLine("Registration failed (code " + registerResult + ")");
    return;
}

Console.WriteLine("Registration response: " + registerResponse);

Step 3: Start a Session

Initialize a terminal session using transaction type 18.

Use the following code to start a session:

timestamp = DateTime.Now.ToString("ddMMyyHHmmss");

string sessionData = $"{timestamp};{terminalId}!";

string sessionResponse;

int sessionResult = ecr.doTCPIPTransaction(
    ipAddress,
    port,
    sessionData,
    18,
    "",
    out sessionResponse
);

if (sessionResult != 0)
{
    Console.WriteLine("Start Session failed (code " + sessionResult + ")");
    return;
}

Console.WriteLine("Start Session response: " + sessionResponse);

Step 4: Execute a Purchase Transaction

Execute a purchase transaction using transaction type 0.

Use the following code to process a payment:

decimal amount = 33.00m;

int amountMinorUnits = (int)(amount * 100);

timestamp = DateTime.Now.ToString("ddMMyyHHmmss");

string purchaseData =
    $"{timestamp};{amountMinorUnits};0;{terminalId}{newEcrRef:P6}!";

string signature =
    ecr.ComputeSha256Hash(newEcrRef.ToString("D6") + terminalId);

string purchaseResponse;

int purchaseResult = ecr.doTCPIPTransaction(
    ipAddress,
    port,
    purchaseData,
    0,
    signature,
    out purchaseResponse
);

if (purchaseResult != 0)
{
    Console.WriteLine("Purchase failed (code " + purchaseResult + ")");
    return;
}

Console.WriteLine("Purchase response: " + purchaseResponse);

Step 5: Disconnect the Terminal

Disconnect the terminal when communication is complete.

Use the following code to disconnect the terminal:

int disconnectResult = ecr.doTCPIPDisconnection();

if (disconnectResult != 0)
{
    Console.WriteLine("Disconnection failed (code " + disconnectResult + ")");
}
else
{
    Console.WriteLine("Disconnected successfully.");
}

Serial (COM) Communication

Step 1: Establish COM Connection

Connect to the terminal through a serial COM port.

Use the following code to establish a COM connection:

using CoreSkybandECR;

InteroperableService obj = new InteroperableService();

int result = obj.doCOMConnection(
    3,
    "115200",
    "None",
    8,
    1
);

Step 2: Register the Terminal

Register the terminal using transaction type 17.

Use the following code to register the terminal:

string registerRequest = "250720114240;12345678!";

int request = obj.doCOMTransaction(
    3,
    "115200",
    "None",
    8,
    1,
    registerRequest,
    17,
    "",
    out string response
);

Step 3: Start a Session

Start a terminal session using transaction type 18.

Use the following code to start a session:

string sessionRequest = "250720114240;12345678!";

int request = obj.doCOMTransaction(
    3,
    "115200",
    "None",
    8,
    1,
    sessionRequest,
    18,
    "",
    out string response
);

Step 4: Execute a Purchase Transaction

Execute a purchase transaction using transaction type 0.

Use the following code to process a payment:

string purchaseRequest =
    "250720114732;33;0;12345678000002!";

string signature =
    "332fe9220710e21f21878fbd5776e871c363b0d8ed4d4fab685622937bf2d074";

int request = obj.doCOMTransaction(
    3,
    "115200",
    "None",
    8,
    1,
    purchaseRequest,
    0,
    signature,
    out string response
);

Step 5: Disconnect the Terminal

Disconnect the terminal when communication is complete.

Use the following code to disconnect the terminal:

int result = obj.doCOMDisconnection();

Response Handling

Transaction responses are returned through the response output parameter as a CSV string.

Responses typically contain:

• Response Code
• Approval Status
• Transaction Amount
• Timestamp
• ECR Reference Number
• Receipt Data

Example Response

00,APPROVED,3300,140524193012,TX12345678,RECEIPT123

Parsed Response Fields

Response Parsing Example

string response =
    "00,APPROVED,3300,140524193012,TX12345678,RECEIPT123";

string[] fields = response.Split(',');

string responseCode = fields[0];
string approvalStatus = fields[1];
string amount = fields[2];
string timestamp = fields[3];
string ecrReference = fields[4];
string receiptData = fields[5];

Error Handling

Verify the following if a connection or transaction fails:

• Terminal IP address and port number.
• Network connectivity between the Merchant Application and terminal.
• COM port number and serial communication settings.
• Firewall or endpoint security restrictions.
• ECR.dll availability in the application output directory.
• Request format and delimiter placement.
• Terminal ID value.
• ECR reference number format.
• SHA-256 signature generation logic.
• Explicitly copy ECR.dll to the application output directory. Missing DLLs cause runtime errors.
• Use the SDK’s built‑in logging (e.g., Serilog) or custom diagnostic logs. Capture low‑level serial or network hex packet streams for debugging.

Ensure:

• Registration and session requests end with !.
• Semicolon (;) separators are present in the correct positions.
• TCP/IP transaction amounts are sent in minor units.
• ECR reference numbers remain unique across transactions.
• The signature is generated using the ECR reference number and terminal ID.

Key Rules

• Establish a connection before sending transaction requests.
• Register the terminal before starting a session.
• Start a session before executing a purchase transaction.
• Use transaction type 17 for terminal registration.
• Use transaction type 18 for session initialization.
• Use transaction type 0 for purchase transactions.
• Use a unique ECR reference number for each transaction.
• Disconnect the terminal when communication is complete.

Final Integration Flow

Connect Terminal
↓
Register Terminal
↓
Start Session
↓
Execute Purchase Transaction
↓
Receive Response
↓
Parse Response
↓
Disconnect Terminal

Installation Notes

• Requires .NET Framework 4.8 or later.
• Requires CoreSkybandECR.dll.
• Requires ECR.dll.
• ECR.dll must be copied explicitly to the application output directory to prevent runtime errors.
• A compatible Nami Payment Terminal is required.
• TCP/IP or Serial (COM) communication must be configured before integration.