SDK Response Codes & Error Handling

class KoardException(
    cause: Throwable? = null,
    val error: KoardError
) : Throwable(error.shortMessage, cause)

data class KoardError(
    val shortMessage: String,      // Human-readable error description
    val errorType: KoardErrorType  // Typed error classification (sealed hierarchy)
)

try {
    sdk.capture(transactionId, amount)
} catch (e: KoardException) {
    when (e.error.errorType) {
        is KoardErrorType.KoardServiceErrorType.HttpError -> {
            val code = (e.error.errorType as KoardErrorType.KoardServiceErrorType.HttpError).errorCode
            showError("Server error (HTTP $code): ${e.error.shortMessage}")
        }
        is KoardErrorType.KoardServiceErrorType.ConnectionError ->
            showError("Network error — check your connection")
        is KoardErrorType.KoardServiceErrorType.Unauthorized ->
            showError("Session expired — please log in again")
        is KoardErrorType.VACEnrollmentError ->
            showError("Enrollment failed — re-enroll the device")
        else ->
            showError(e.error.shortMessage)
    }
}

when (response.actionStatus) {
    KoardTransactionActionStatus.OnProgress -> {
        showStatus(response.readerStatus.toString(), response.displayMessage)
    }
    KoardTransactionActionStatus.OnFailure -> {
        showError(response.statusCode, response.displayMessage ?: "Transaction failed")
    }
    KoardTransactionActionStatus.OnComplete -> {
        when (response.finalStatus) {
            KoardTransactionFinalStatus.Approve  -> showReceipt(response.transaction!!)
            KoardTransactionFinalStatus.Decline  -> showDeclined(response)
            KoardTransactionFinalStatus.Abort    -> showAborted(response)
            KoardTransactionFinalStatus.Failure  -> showFailure(response)
        }
    }
}

private fun handleTransactionEvent(response: KoardTransactionResponse) {
    when (response.actionStatus) {
        KoardTransactionActionStatus.OnProgress -> {
            // Update UI with reader status and display message
            updateUI(
                status = response.readerStatus.toString(),
                message = response.displayMessage ?: "Processing..."
            )
        }

        KoardTransactionActionStatus.OnFailure -> {
            // Check for re-enrollment scenario
            if (response.statusCode == 12) {
                // Tap to Pay Ready app was reinstalled or cleared data
                // Clear stored enrollment info and re-run enrollment
                triggerReEnrollment()
                return
            }

            // Transaction could not proceed — show the reason
            val reason = buildString {
                append("Transaction Failed")
                response.displayMessage?.let { append("\n\n$it") }
                response.statusCodeDescription?.let { append("\n\n$it") }
                response.statusCode?.let { append("\n\nStatus Code: $it") }
            }
            showError(reason)
        }

        KoardTransactionActionStatus.OnComplete -> {
            when (response.finalStatus) {
                KoardTransactionFinalStatus.Approve -> {
                    showReceipt(response.transaction!!)
                }
                KoardTransactionFinalStatus.Decline -> {
                    showDeclined(response.displayMessage ?: "Transaction declined")
                }
                KoardTransactionFinalStatus.Abort -> {
                    showAborted(response.displayMessage ?: "Transaction aborted")
                }
                KoardTransactionFinalStatus.Failure -> {
                    showError(response.displayMessage ?: "Transaction failed")
                }
                is KoardTransactionFinalStatus.Unknown -> {
                    showError("Unexpected status: ${response.finalStatus}")
                }
            }
        }

        else -> Unit
    }
}

private suspend fun capturePayment(transactionId: String, amount: Int) {
    try {
        val result = sdk.capture(transactionId, amount)
        showReceipt(result)
    } catch (e: KoardException) {
        when (val errorType = e.error.errorType) {
            // HTTP errors from the Koard API
            is KoardErrorType.KoardServiceErrorType.HttpError ->
                showError("Server error (HTTP ${errorType.errorCode}): ${e.error.shortMessage}")
            is KoardErrorType.KoardServiceErrorType.ConnectionError ->
                showError("Network error — check your connection and retry")
            is KoardErrorType.KoardServiceErrorType.Unauthorized ->
                showError("Session expired — please log in again")
            is KoardErrorType.KoardServiceErrorType.NotFound ->
                showError("Transaction not found")
            is KoardErrorType.KoardServiceErrorType.InvalidRequest ->
                showError("Invalid request: ${e.error.shortMessage}")

            // Device integrity failures
            is KoardErrorType.DeviceIntegrityError.DeveloperModeEnabled ->
                showError("Disable developer mode before processing payments")
            is KoardErrorType.DeviceIntegrityError ->
                showError("Device security check failed: ${e.error.shortMessage}")

            // Enrollment issues
            is KoardErrorType.VACEnrollmentError ->
                promptReEnrollment(e.error.shortMessage)
            is KoardErrorType.VACEligibilityError ->
                showError("Device not eligible for Tap to Pay: ${e.error.shortMessage}")

            // KiC connector/kernel errors
            is KoardErrorType.KicConnectorError.KernelAppNotInstalled ->
                showError("Install the Visa Tap to Pay Ready app from Google Play")
            is KoardErrorType.KicConnectorError ->
                showError("Kernel communication error: ${e.error.shortMessage}")
            is KoardErrorType.KicPrepareError.SdkEnrollNotDone ->
                promptReEnrollment("Device needs re-enrollment")

            // Fallback
            else -> showError(e.error.shortMessage)
        }
    }
}