The Nami ECR .NET SDK enables a .NET-based Merchant Application to communicate with a Nami Payment Terminal. The SDK provides APIs for terminal registration, session management, payment processing, and communication over TCP/IP or Serial (COM) interfaces.

For integration steps, refer to .Net Integration.

The SDK abstracts low-level communication and allows applications to initiate payment transactions and receive transaction responses through standardized protocols.

Prerequisites

Ensure that the following requirements are met before integrating the SDK.

Installation Requirements

Add Managed Library

Add the CoreSkybandECR library to the project.

1. Open Visual Studio.
2. Open the project solution.
3. Right-click References.
4. Select Add Reference.
5. Browse and select CoreSkybandECR.dll.

Add Native Library

Add the ECR native library to the project.

1. Right-click the project.
2. Select Add > Existing Item.
3. Browse and select ECR.dll.

Configure Output Directory

Select ECR.dll and set:

Copy to Output Directory = Always

The ECR.dll file must be available in the application output directory during runtime.

Required Libraries

Supported Communication Methods

Architecture Overview

The Merchant Application communicates with the Payment Terminal through the SDK.

Merchant Application
        ↓
CoreSkybandECR SDK
        ↓
Nami Payment Terminal

All terminal communication is performed through the InteroperableService class.

Core Namespace

Include the following namespace before using the SDK.

using CoreSkybandECR;

Core Class Reference

InteroperableService

The InteroperableService class provides all communication and transaction APIs.

Use the following code to create an SDK instance:

InteroperableService ecr = new InteroperableService();

API Summary

Method Reference

doTCPIPConnection()

Establishes a TCP/IP connection with the Payment Terminal.

int doTCPIPConnection(string ipAddress, int portNumber);

Parameters

Return Value

doTCPIPTransaction()

Sends a transaction request through an established TCP/IP connection.

int doTCPIPTransaction(
    string ipAddress,
    int portNumber,
    string inputReqData,
    int transactionType,
    string szSignature,
    out string res
);

Parameters

Return Value

Returns a transaction processing status code.

doTCPIPDisconnection()

Disconnects the active TCP/IP connection.

int doTCPIPDisconnection();

Return Value

doCOMConnection()

Establishes a Serial (COM) connection with the Payment Terminal.

int doCOMConnection(
    int Port,
    string baudRate,
    string parity,
    int dataBits,
    int stopBits
);

Return Value

doCOMTransaction()

Sends a transaction request through a Serial (COM) connection.

int doCOMTransaction(
    int Port,
    string baudRate,
    string parity,
    int dataBits,
    int stopBits,
    string inputReqData,
    int transactionType,
    string szSignature,
    out string res
);

Return Value

Returns a transaction processing status code.

doCOMDisconnection()

Disconnects the active COM port session.

int doCOMDisconnection();

Return Value

ComputeSha256Hash()

Generates a SHA-256 hash value.

string ComputeSha256Hash(string input);

Parameters

Return Value

Returns a SHA-256 hash string.

COM Communication Parameters

COM Connection Return Values

COM Disconnection Return Values

Transaction Type Codes

Terminal Registration

Transaction Type 17 identifies the Merchant Application and terminal to the Payment Terminal.

Session Start

Transaction Type 18 starts a secure session after registration.

Purchase Transaction

Transaction Type 0 performs a payment transaction.

Request Payload Formats

Registration and Session Request

This payload format is used for:

• Terminal Registration (Transaction Type 17)
• Session Start (Transaction Type 18)

Format

DDMMYYHHMMSS;TerminalID!

Components

Example

250720114240;12345678!

Purchase Transaction Request

Format

DDMMYYHHMMSS;AmountMinor;0;TerminalIDEcrRef!

Components

Amount Format

For TCP/IP transactions:

33.00 → 3300

For COM transactions, the documentation specifies the raw amount format:

33

Example

250720114732;3300;0;12345678000002!

Response Handling

Transaction responses are returned through:

out string res

The response contains the raw data returned by the Payment Terminal.

Applications are responsible for parsing and processing the response.

Security & Signatures

Purchase transactions require SHA-256 signature validation.

Registration and Session Start transactions do not require signatures.

Signature Generation

Use the following method:

string signature = ComputeSha256Hash(input);

Signature Format

SHA256(EcrRef + TerminalID)

Signature Rules

The signature is generated by concatenating the EcrRef value and TerminalID value.

EcrRef must:

• Be unique for each transaction
• Increment from the previous transaction
• Be zero-padded to six digits

Example:

000002

The generated SHA-256 value must be passed through the szSignature parameter.

Transactions Requiring Signatures

Configuration Persistence

The SDK does not provide APIs for configuration storage.

Applications are responsible for storing and retrieving:

• Terminal IP address
• Port number
• COM port settings
• Terminal ID
• Merchant-specific configuration

Configuration values must be supplied when invoking SDK APIs.

Runtime Behaviors

SDK Instance

All SDK operations are performed through the InteroperableService class.

InteroperableService ecr = new InteroperableService();

Communication Modes

The SDK supports:

• TCP/IP communication
• Serial (COM) communication

Response Processing

Transaction responses are returned through:

out string res

Applications are responsible for processing the returned response.

Connection Lifecycle

A typical SDK communication lifecycle is:

Connect
↓
Execute Transaction
↓
Receive Response
↓
Disconnect

Error Handling

All SDK methods return integer status values.

Connection Errors

The following methods return connection status codes:

• doTCPIPConnection()
• doCOMConnection()

Transaction Errors

The following methods return transaction status codes:

• doTCPIPTransaction()
• doCOMTransaction()

Applications should verify:

• Method return values
• Response data returned by the SDK

Disconnection Errors

The following methods return disconnection status codes:

• doTCPIPDisconnection()
• doCOMDisconnection()

A non-zero return value indicates that the disconnection operation failed.

Transaction Flow

The SDK supports the following transaction sequence:

Terminal Registration (17)
↓
Session Start (18)
↓
Purchase Transaction (0)
↓
Receive Terminal Response
↓
Process Response
↓
Disconnect