TerminalSDK Library Documentation

implementation("io.nearpay:terminalsdk-debug:0.0.38")
implementation("com.google.android.gms:play-services-location:20.0.0")
implementation("com.huawei.hms:location:6.4.0.300")

    android {
        defaultConfig {
            applicationId = "com.example.terminalSDK1"
            minSdk = 28
            targetSdk = 30
            versionCode = 1
            versionName = "75"
        }
    }

// initializing the terminalSDK may throw an exception, so wrap it in a try-catch block
try {
    val nearpay = TerminalSDK.Builder()
        .activity(this)  // Sets the activity context
        .environment(SdkEnvironment.SANDBOX)  // Choose SANDBOX or PRODUCTION
        .googleCloudProjectNumber(12345678)  // Set Google Cloud project number
        .huaweiSafetyDetectApiKey("your_api_key")  // Set Huawei API key
        .country(Country.SA)  // Set country
        .build()
    } catch (e: Throwable) {
        Timber.e("Error initializing TerminalSDK: $e")
    }

// Check all required permissions
val permissionStatuses = nearpay.checkRequiredPermissions()
permissionStatuses.forEach { status ->
    if (!status.isGranted) {
        // Handle missing permission
        Log.d("Permissions", "Missing permission: ${status.permission}")
    }
}

var PERMISSIONS_REQUEST_CODE = 0
// Check permissions
val missingPermissions = nearpay.checkRequiredPermissions()
    .filter { !it.isGranted }
    .map { it.permission }

if (missingPermissions.isNotEmpty()) {
// Request missing permissions
ActivityCompat.requestPermissions(
this,
missingPermissions.toTypedArray(),
PERMISSIONS_REQUEST_CODE //0 for example
)
}

// Check NFC
if (!nearpay.isNfcEnabled(this)) {
Log.d("MainActivity", "NFC is disabled");
}

// Check WiFi
if (!nearpay.isWifiEnabled(this)) {
Log.d("MainActivity", "WiFi is disabled");
}

val mobileLogin = MobileLogin("+966532996473")
nearpay.sendOTP(mobileLogin, object : SendOTPMobileListener {
    override fun onSendOTPMobileSuccess(otpResponse: OtpResponse) {
        Log.d("Login", " onSendOTPMobileSuccess ($otpResponse)")
    }
    override fun onSendOTPMobileFailure(otpMobileFailure: OTPMobileFailure) {
        Log.d("Login", " onSendOTPMobileFailure ($otpMobileFailure)")
    }
})

val emailLogin = EmailLogin("[email protected]")
nearpay.sendOTP(emailLogin, object : SendOTPEmailListener {
    override fun onSendOTPEmailSuccess(otpResponse: OtpResponse) {
        Log.d("Login", " onSendOTPEmailSuccess ($otpResponse)")
    }
    override fun onSendOTPEmailFailure(otpEmailFailure: OTPEmailFailure) {
        Log.d("Login", " onSendOTPEmailFailure ($otpEmailFailure)")
    }
})

val loginData = LoginData(
    mobile = "+966532996473",
    code = "123456"
)
nearpay.verify(loginData, object : VerifyMobileListener {
    override fun onVerifyMobileSuccess(user: User) {
        Log.d("Login", " onVerifyMobileSuccess ($user.name)")
    }
    override fun onVerifyMobileFailure(verifyMobileFailure: VerifyMobileFailure) {
        Log.d("Login", " onVerifyMobileFailure ($failure)")
    }
})

val loginData = LoginData(
    email = "[email protected]",
    code = "123456"
)
nearpay.verify(loginData, object : VerifyEmailListener {
    override fun onVerifyEmailSuccess(user: User) {
        Log.d("Login", " onVerifyEmailSuccess ($user.name)")
    }
    override fun onVerifyEmailFailure(verifyEmailFailure: VerifyEmailFailure) {
        Log.d("Login", " onVerifyEmailFailure ($verifyMobileFailure)")
    }
})

val loginData = JWTLoginData(
    jwt = "jwt_token"
)
nearpay.jwtLogin(loginData, object : JWTLoginListener {
            override fun onJWTLoginSuccess(terminal: Terminal) {
                Log.d("Login", "JWT Login success + ${terminal.terminalUUID}")
            }

            override fun onJWTLoginFailure(jwtLoginFailure: JWTLoginFailure) {
                Log.d("Login", "JWT Login failure: $jwtLoginFailure")
            }
        })

try{
    val user = nearpay.getUserByUUID(uuid)
} catch (e: Exception) {
    Log.d("UserSDK", "User connection failed: ${e}")
}
// The returned user object also becomes the active user

try {
    nearpay.logout(uuid)
} catch (e: Exception) {
    Log.d("UserSDK", "User logout failed: ${e}")
}

lateinit var firstTerminal: Terminal
userInstance.listTerminals(
    page = 1,
    pageSize = 10,
    filter = null, // You can pass the terminal ID to get a specific terminal
    object : GetTerminalsListener {
        override fun onGetTerminalsSuccess(terminalsConnection: List<TerminalConnection>) {
            // Handle success
            terminalsConnection.firstOrNull()?.let { terminal ->
                // Access terminal data
                val terminalName = terminal.terminalConnectionData.name
                // Update UI or store reference
                firstTerminal = terminal
            }
        }

        override fun onGetTerminalsFailure(getTerminalsFailure: GetTerminalsFailure) {
            // Handle failure
            Log.d("Terminals", "Terminals list failure: $getTerminalsFailure")
        }
    },
    )

firstTerminal.connect(
    activity = this,
    listener = object : ConnectTerminalListener {
        override fun onConnectTerminalSuccess(terminal: Terminal) {
            // Terminal connected successfully
            // Store terminal instance for future operations
            terminalInstance = terminal
        }

        override fun onConnectTerminalFailure(connectTerminalFailure: ConnectTerminalFailure) {
            // Handle failure
            Log.d("Terminal", "Terminal connection failed: $connectTerminalFailure")
        }
    }
)

try {
private var tid: String = "058594894-4545945-45454"
val terminalInstance = nearpay.getTerminal(
    activity = this,
    tid = tid
)
} catch (e: Exception) {
     Log.d("TerminalSDK", "Terminal connection failed: ${e}")
}

    var amount = 100
    var transactionUUID = UUID.randomUUID().toString()
terminal.purchase(
    amount = amount,
    scheme = null, // eg.PaymentScheme.VISA, specifying this as null will allow all schemes to be accepted
    transactionUUID = transactionUUID // the transaction UUID should be unique for each transaction and managed by the developer to communicate with the SDK
    readCardListener = object : ReadCardListener {
        override fun onReadCardSuccess() {
            // Card read successfully
            Log.d("ReadCard", "Card read successfully")
        }

    // Called when the card reading process fails - issues with the specific card or its interaction
    // Examples: card removed too quickly, unreadable card, wrong card orientation
        override fun onReadCardFailure(readCardFailure: ReadCardFailure) {
            // Handle card read failure
            Log.d("ReadCard", "Card read failure: $readCardFailure")
        }

        override fun onReaderWaiting() {
            // Reader waiting for card
            Log.d("ReadCard", "Reader waiting for card")
        }

        override fun onReaderReading() {
            // Reading card in progress
            Log.d("ReadCard", "Reading card in progress")
        }

        override fun onReaderRetry() {
            // Reader retry needed
            Log.d("ReadCard", "Reader retry needed")
        }

        override fun onPinEntering() {
            // PIN entry in progress
            Log.d("ReadCard", "PIN entry in progress")
        }

        override fun onReaderFinished() {
            // Card read completed
            Log.d("ReadCard", "Card read completed")
        }
        override fun onReadingStarted() {
            // Card read started
            Log.d("ReadCard", "Card read started")
        }

    // Called when the card reader device itself encounters an error
    // Examples: hardware malfunction, connection issues, device not ready
        override fun onReaderError(error: String?) {
            // Handle reader error
            Log.d("ReadCard", "Reader error: $error")
        }
    },
    sendTransactionListener = object : SendTransactionListener {
        override fun onSendTransactionSuccess(response: TransactionResponse) {
            // Handle successful transaction
            Log.d("Transaction", "Transaction success: $response")
        }

        override fun onSendTransactionFailure(failure: SendTransactionFailure) {
            // Handle transaction failure
            Log.d("Transaction", "Transaction failure: $failure")
        }
    }
)

    var amount = 1000L
    var transactionUUID = "1234567890"
    var refundUUID = UUID.randomUUID().toString()

terminal.refund(
    amount = amount,
    scheme = null, // eg.PaymentScheme.VISA, specifying this as null will allow all schemes to be accepted
    transactionUUID = transactionUUID, // the same transaction UUID used in the purchase transaction
    refundUUID = refundUUID, // the refund UUID should be unique for each refund transaction and managed by the developer to communicate with the SDK
    readCardListener = object : ReadCardListener {
        // Card reading callbacks
        // Same implementation as purchase
    },
    refundTransactionListener = object : RefundTransactionListener {
        override fun onRefundTransactionSuccess(transactionResponse: TransactionResponse) {
            // Handle successful refund
            Log.d("Refund", "Refund success: $transactionResponse")
        }

        override fun onRefundTransactionFailure(refundTransactionFailure: RefundTransactionFailure) {
            // Handle refund failure
            Log.d("Refund", "Refund failure: $refundTransactionFailure")
        }
    }
)

var transactionUUID = "transaction-uuid"

terminal.cancelTransaction(
    id = transactionUUID, // Transaction ID
    cancelTransactionListener = object : CancelTransactionListener {
        override fun onCancelTransactionSuccess(canceledState : CanceledState) {
            Log.d("Cancel", "Transaction Cancelled: ${canceledState.canceled}")
        }

        override fun onCancelTransactionFailure(cancelTransactionFailure: CancelTransactionFailure) {
            Log.d("Cancel", "Transaction Cancelled Failure: $cancelTransactionFailure")
        }
    }
)

var transactionUUID = "transaction-uuid"
terminal.reverseTransaction(
        id = transactionUUID,
        object : ReverseTransactionListener {
            override fun onReverseTransactionSuccess(transactionResponse: TransactionResponse) {
                CoroutineScope(Dispatchers.Main).launch {
                    Log.d("Transaction", "Transaction reversed: $transactionResponse")
                }
            }

            override fun onReverseTransactionFailure(reverseTransactionFailure: ReverseTransactionFailure) {
                    Log.d("Transaction", "Transaction reverse failure: $reverseTransactionFailure")

            }

        }
    )

var transactionID = "transaction-id"
terminal.getTransaction(
    transactionID, // Transaction ID
    getTransactionListener = object : GetTransactionListener {
        override fun onGetTransactionSuccess(transaction: ReceiptsResponse) {
            Log.d("Transaction", "Transaction Details: $transaction")
        }

        override fun onGetTransactionFailure(error: GetTransactionFailure) {
            Log.d("Transaction", "Transaction Details Failure: $error")
        }
    }
)

terminal.getTransactionsList(
    page = 1,
    pageSize = 10,
    isReconciled = true, // do not specify it if all transactions are needed
    startDate = 1733961600000, endDate = 1735084800000, // Optional date range in timestamp format
    customerReferenceNumber = "customer_reference_number", // Optional customer reference number
    getTransactionsListListener = object : GetTransactionsListListener {
        override fun onGetTransactionsListSuccess(transactionsList: TransactionsResponse) {
            Log.d("Transactions", "Transactions List: $transactionsList")
        }

        override fun onGetTransactionsListFailure(error: GetTransactionsListFailure) {
            Log.d("Transactions", "Transactions List Failure: $error")
        }
    }
)

terminal.reconcile(
    reconcileListener = object : ReconcileTransactionListener {
        override fun onReconcileTransactionSuccess(reconciliationReceiptsResponse: ReconciliationReceiptsResponse) {
            // Handle success
            Log.d("Reconcile", "Reconcile Success: $reconciliationReceiptsResponse")
        }

        override fun onReconcileTransactionFailure(reconcileTransactionFailure: ReconcileTransactionFailure) {
            // Handle failure
            Log.d("Reconcile", "Reconcile Failure: $reconcileTransactionFailure")
        }
    }
)

terminal.getReconciliationList(
    page = 1,
    pageSize = 10,
    startDate = null, //in timestamp format
    endDate = null, //in timestamp format
    getReconciliationListListener = object : GetReconciliationListListener {
        override fun onGetReconciliationListSuccess(reconciliationListResponse: ReconciliationListResponse) {
            // Handle success
            Log.d("Reconciliation", "Reconciliation List: $reconciliationListResponse")
        }

        override fun onGetReconciliationListFailure(error: GetReconciliationListFailure) {
            // Handle failure
            Log.d("Reconciliation", "Reconciliation List Failure: $error")
        }
    }
)

terminal.getReconciliation(
    "reconciliation-id", // Reconciliation ID
    getReconciliationListListener = object : GetReconciliationListener {
        override fun onGetReconciliationSuccess(reconciliationReceiptsResponse: ReconciliationReceiptsResponse) {
            // Handle success
            Log.d("handleReadCard", "GetReconciliation success $reconciliationReceiptsResponse")
        }

        override fun onGetReconciliationFailure(error: GetReconciliationFailure) {
            // Handle failure
            Log.d("handleReadCard", "GetReconciliation failure $error")
        }
    }
)