Atom NEXT API Reference

Version History​

Table of Contents​

• Atom NEXT API Reference
  • Version History
  • Table of Contents
  • Overview
  • Quick Start (Recommended: AtomNext)
    • 1) Initialize
    • 2) Start a transaction
    • 3) Release
  • API Methods (Recommended Layer: AtomNext)
    • init(param: Bundle?, listener: AtomNextListener): Unit
    • transact(params: Bundle, listener: TransactionListener): Unit
    • release(): Unit
  • API Methods (AIDL Layer)
    • initialize(in Bundle bundle, IBinder appBinder, TransactionListener listener): void
    • finalize(in Bundle bundle): void
    • transact(in Bundle bundle, TransactionListener listener): void
  • Bundle Keys (KeyConst)
    • Init Bundle
    • Transaction Request Bundle
    • Result Bundle
  • transName Values (InvokeTransName)
  • Validation Matrix (Current Implementation)
  • Result Callback Fields
    • Common
  • Error Codes (Errors)
  • Kotlin Example
  • Best Practices
  • External Call Examples (Non-AIDL)
    • 1. RESTful API Example (CURL)
      • Transaction Request (Consume)
      • Initialization
    • 2. Socket Example (Kotlin/JVM)
    • 3. RESTful Example (Android/Kotlin)
    • Protocol Notes

Overview​

Atom NEXT provides threeintegration layers:

• Recommended: use the AtomNext helper class (AIDL by default, with optional NET socket mode or restful mode)
• Low-level: bind directly to IAtomNext.aidl

All requests and results use Android Bundle. Results are returned asynchronously through callbacks.

Quick Start (Recommended: AtomNext)​

1) Initialize​

AtomNext.me(context).init(param, listener)

• Success callback: AtomNextListener.onSuccess()
• Failure callback: AtomNextListener.onError(errorCode)

2) Start a transaction​

AtomNext.me(context).transact(params, transactionListener)

• Completion callback: TransactionListener.onTransactionResult(resultBundle)
• Interactive callback: TransactionListener.onInteractiveCallback(callbackBundle) (optional)

3) Release​

AtomNext.me(context).release()

API Methods (Recommended Layer: AtomNext)​

init(param: Bundle?, listener: AtomNextListener): Unit​

Initializes Atom NEXT connectivity.

Syntax

• AtomNext.me(context).init(param, listener)

Parameters

• param (Bundle?): optional initialization bundle.
  • connectionType (Int): 0 (AIDL, default) or 1 (Socket) or 2 (Restful)
  • remoteIp (String): required when connectionType=1 or connectionType=2
  • remotePort (Int): optional when connectionType=1 or connectionType=2, default 5000
• listener (AtomNextListener): initialization callbacks.

Returns

• Unit (asynchronous result via callbacks).

Throws

• No direct exception is exposed by this helper method.

Callbacks

• onSuccess(): initialization completed.
• onError(error: Int): initialization failed or service disconnected.

Notes

• In AIDL mode, service binding target is atomnext-api-service in package com.landiglobal.atomnext.
• In NET mode, connectivity errors are reported through onError.

transact(params: Bundle, listener: TransactionListener): Unit​

Starts a transaction request.

Syntax

• AtomNext.me(context).transact(params, listener)

Parameters

• params (Bundle): transaction input bundle; must include transName.
• listener (TransactionListener): transaction callbacks.

Returns

• Unit (asynchronous result via onTransactionResult).

Throws

• No direct exception is exposed by this helper method.

Callbacks

• onTransactionResult(result: Bundle): final transaction result.
• onInteractiveCallback(result: Bundle): Bundle?: optional interactive callback for two-way interaction.

Notes

• If initialization is not completed, callback returns result = ERROR_INITIALIZE.
• AIDL mode forwards to remote IAtomNext.transact(...).
• NET mode converts Bundle to JSON and sends via socket.

release(): Unit​

Releases resources.

Syntax

• AtomNext.me(context).release()

Parameters

• None.

Returns

• Unit.

Throws

• No direct exception is exposed by this helper method.

Notes

• In AIDL mode, the client calls remote finalize(Bundle()).
• The client unbinds the service and clears local service reference state.

API Methods (AIDL Layer)​

initialize(in Bundle bundle, IBinder appBinder, TransactionListener listener): void​

Initializes the remote Atom NEXT service.

Syntax

• void initialize(in Bundle bundle, IBinder appBinder, TransactionListener listener)

Parameters

• bundle: initialization bundle
• appBinder: caller binder token
• listener: AIDL transaction listener
  • onTransactionFinished(in Bundle result): init result callback
  • onInteractiveCallback(in Bundle callback): Bundle: optional interactive callback

Returns

• void (asynchronous initialization result is returned through onTransactionFinished).

Throws

• RemoteException (at caller side, as part of Binder IPC contract).

finalize(in Bundle bundle): void​

Finalizes and releases service-side resources for the caller.

Syntax

• void finalize(in Bundle bundle)

Parameters

• bundle: finalize options bundle (currently not consumed by implementation).

Returns

• void.

Throws

• RemoteException (at caller side, as part of Binder IPC contract).

transact(in Bundle bundle, TransactionListener listener): void​

Starts a transaction on service side and returns asynchronous result through listener.

Syntax

• void transact(in Bundle bundle, TransactionListener listener)

Parameters

• bundle: transaction request bundle.
• listener: callback listener for final/interactive responses.

Returns

• void (transaction result is asynchronous).

Throws

• RemoteException (at caller side, as part of Binder IPC contract).

Service binding info (AIDL):

• action: atomnext-api-service
• package: com.landiglobal.atomnext

Bundle Keys (KeyConst)​

All keys below are literal values used in Android Bundle.

Init Bundle​

Transaction Request Bundle​

Result Bundle​

transName Values (InvokeTransName)​

Use the exact string values below:

Validation Matrix (Current Implementation)​

Validation rules are implemented in InvokeController.checkOnBeforeStartTrans().

Implementation notes:

• Most key validations are validate-if-present; transaction business flow may still require additional fields.
• TRANS_GET_MERCHANT_INFO_LIST returns merchantInfoList on success.

Result Callback Fields​

Common​

Always check:

• result: result code
• errorMsg: error description on failure (may be empty)

Error Codes (Errors)​

Kotlin Example​

val initBundle = Bundle().apply {
    putInt("connectionType", 0) // 0:AIDL, 1:NET
}

AtomNext.me(context).init(initBundle, object : AtomNextListener {
    override fun onSuccess() {
        val params = Bundle().apply {
            putString("transName", "CONSUME")
            putString("amount", "000000001000")
            putBoolean("maskedCardNo", true)
        }
        AtomNext.me(context).transact(params, object : TransactionListener {
            override fun onTransactionResult(result: Bundle) {
                val code = result.getInt("result")
                val error = result.getString("errorMsg")
                // handle by result code
            }
        })
    }

    override fun onError(error: Int) {
        // initialization failure handling
    }
})

Best Practices​

• Wait for init() success callback before calling transact()
• Always check result; never assume success
• Pass only fields required by the current transaction
• Keep masked PAN by default (maskedCardNo=true)
• Call release() when your component is destroyed or no longer needs Atom NEXT

External Call Examples (Non-AIDL)​

These examples demonstrate how external clients (e.g., a Windows PC or another Android device) can interact with Atom NEXT services over the network.

1. RESTful API Example (CURL)​

The RESTful service listens for POST requests. In Windows CMD, you must escape double quotes with a backslash \".

Transaction Request (Consume)​

• URL: http://{DEVICE_IP}:5000/api/v1/transact
• Method: POST
• Body: JSON

curl -X POST http://172.26.110.38:9000/api/v1/transact ^
     -H "Content-Type: application/json" ^
     -d "{\"transName\": \"CONSUME\", \"amount\": \"000000001000\"}"

Initialization​

• URL: http://{DEVICE_IP}:5000/api/v1/init

curl -X POST http://172.26.110.38:9000/api/v1/init -H "Content-Type: application/json" -d "{}"

2. Socket Example (Kotlin/JVM)​

The Socket service expects a JSON string. The connection is typically closed by the server after the response is sent.

import java.net.Socket
import java.io.InputStream
import java.io.OutputStream

fun callSocketTransaction(ip: String, port: Int) {
    try {
        Socket(ip, port).use { socket ->
            val output: OutputStream = socket.getOutputStream()
            val input: InputStream = socket.getInputStream()

            // 1. Prepare Request JSON
            val requestJson = """
                {
                    "transName": "CONSUME",
                    "amount": "000000001000",
                    "maskedCardNo": true
                }
            """.trimIndent()

            // 2. Send Data
            output.write(requestJson.toByteArray(Charsets.UTF_8))
            output.flush()

            // 3. Read Response
            val buffer = ByteArray(4096)
            val bytesRead = input.read(buffer)
            if (bytesRead != -1) {
                val responseJson = String(buffer, 0, bytesRead, Charsets.UTF_8)
                println("Response from POS: ${responseJson}")
            }
        }
    } catch (e: Exception) {
        e.printStackTrace()
    }
}

3. RESTful Example (Android/Kotlin)​

This standard implementation uses HttpURLConnection. In a real production app, consider using libraries like OkHttp or Retrofit.

import java.io.OutputStreamWriter
import java.net.HttpURLConnection
import java.net.URL
import java.util.Scanner

    fun callRestApi(ip: String, port: Int, transName: String, amount: String) {
        Thread {
            try {
                val url = URL("http://${ip}:${port}/api/v1/transact")
                val conn = url.openConnection() as HttpURLConnection
                conn.requestMethod = "POST"
                conn.setRequestProperty("Content-Type", "application/json")
                conn.doOutput = true
                conn.connectTimeout = 5000
                conn.readTimeout = 65000 // Transactions may take time

                // 1. Send Request
                val jsonInput = "{\"transName\": \"${transName}\", \"amount\": \"${amount}\"}"
                conn.outputStream.use { os ->
                    OutputStreamWriter(os, "UTF-8").use { writer ->
                        writer.write(jsonInput)
                        writer.flush()
                    }
                }

                // 2. Read Response
                val responseCode = conn.responseCode
                val responseStream = if (responseCode == HttpURLConnection.HTTP_OK) {
                    conn.inputStream
                } else {
                    conn.errorStream
                }

                Scanner(responseStream, "UTF-8").useDelimiter("\\A").use { s ->
                    val result = if (s.hasNext()) s.next() else ""
                    println("HTTP Response (${responseCode}): ${result}")
                }

            } catch (e: Exception) {
                e.printStackTrace()
            }
        }.start()
    }

Protocol Notes​

• Encoding: All JSON strings should be encoded in UTF-8.
• Port Management: Default ports are configured via ThirdPartyApiServer. Standard is 5000.
• Timeouts: Ensure your client has a sufficient timeout (at least 60 seconds) as financial transactions involve hardware interaction and user input.