SDK Response Codes & Transaction Outcomes

This page covers reader events and transaction outcomes from Android SDK 1.0.7. For exceptions and the released KoardException / KoardErrorType mapping, see SDK Error Codes. For device recovery steps, see Troubleshooting.

Error Model Overview

Catch exceptions around both the SDK invocation and Flow collection: readiness failures can occur before a Flow is returned. For methods returning Result, inspect the failure or call getOrThrow() within try/catch. Reader events instead carry actionStatus, finalStatus, and diagnostic statusCode values.

Transaction Response Flow

KoardTransactionResponse emitted by sdk.sale() or sdk.preauth() can include an action status that tells your app what stage the transaction is in. When present, use this to drive your UI:

Action Status Meaning What to do
OnProgress Transaction is in flight: the reader is active Update your UI with the current displayMessage and readerStatus
OnFailure Read failure or terminal failure A retryable hint with no final status keeps the same flow active; otherwise retain any transaction and display the failure
OnComplete The reader session has finished Inspect transaction.status and nullable finalStatus, including partial approval and surcharge decisions

Use the complete Running Payments handler. Do not force-unwrap response.transaction, assume finalStatus is always present, or show an approved receipt before checking partial and surcharge states.

Final Transaction Statuses

When present on completion, finalStatus has one of these values. It can be null; the returned transaction still carries its persisted status:

Final Status Description Typical Cause
Approve Transaction was authorized by the issuer Successful payment: display receipt with approval code and transaction details
Decline Transaction was explicitly declined Issuer denied the authorization, card restricted, insufficient funds, or Strong CVM required (SCA interface switch)
Abort Transaction was terminated before completion User cancelled, PIN entry cancelled, device security issue, NFC read failure, timeout, or network loss
Failure An internal or system-level error prevented the transaction SDK/reader service error, device misconfiguration, or unexpected processing failure
AltService Card requested an alternative service The card network indicated that an alternative acceptance method should be used
Unknown(rawStatus) The reader service returned a status the SDK could not map Inspect rawStatus for the original value; treat as a non-approval

The SDK consolidates the underlying processor response into these statuses so your app does not need to interpret raw processor-level codes. The original acquirer responseCode (ISO 8583 field 39) is still available in the transaction receipt for logging and support purposes.

Persisted Transaction Status

The reader finalStatus above describes the outcome of a single tap. The persisted transaction itself (KoardTransaction.status, also returned by getTransaction/getTransactions and post-reader operations) uses the KoardTransactionStatus enum:

Status Description
PENDING Transaction created but not yet finalized
AUTHORIZED Funds authorized (preauth/hold)
CAPTURED Authorization captured/settled
SETTLED Settled with the processor
DECLINED Declined by the issuer
REFUNDED Fully or partially refunded
REVERSED Reversed/voided
CANCELED Canceled before completion
ERROR Errored out
SURCHARGE_PENDING Awaiting customer surcharge confirmation: call sdk.confirm(transactionId, confirm = ...)
UNKNOWN Unmapped status

A transaction is refundable when its status is AUTHORIZED, CAPTURED, SETTLED, or PENDING (exposed as KoardTransactionStatus.isRefundable).

Acquirer Authorization Statuses

Behind the scenes, the acquirer returns a more granular authStatus in the authorization response. The SDK maps these to the final statuses above, but they are available in the transaction details for advanced use cases:

Auth Status Description Maps to Final Status
Approve Issuer approved the transaction Approve
Decline Issuer declined the transaction (also used for internal acquirer errors) Decline
PartialApproval Issuer approved a lesser amount than requested Approve (with reduced authorizedAmount)
InvalidPIN The PIN entered by the cardholder was incorrect Decline
UnableToGoOnline The terminal could not connect to the acquirer for online authorization Decline or Abort
AdditionalInfo Acquirer returned supplementary information (e.g., referral) Varies

Transaction Response Details

When a transaction completes (regardless of outcome), the KoardTransactionResponse contains the following fields:

Field Type Description
transactionId String? Unique identifier for the transaction, when available
finalStatus KoardTransactionFinalStatus? Terminal outcome, when available: Approve, Decline, Abort, Failure, or AltService
actionStatus KoardTransactionActionStatus? Current action phase, when available: OnProgress, OnFailure, or OnComplete
readerStatus KoardReaderStatus Reader state: preparing, readyForTap, cardDetected, processing, complete, etc.
displayMessage String? Human-readable message from the reader
statusCode Int? Numeric status code from the reader; see Status Code Reference below
statusCodeDescription String? Human-readable description of the status code (auto-generated from the code)
transaction KoardTransaction? Full transaction object (populated on completion)

Status Code Reference

The statusCode field on KoardTransactionResponse is a numeric integer forwarded from the SDK's reader session. These codes are passed through on the transaction response for troubleshooting and logging.

Wrapped exceptions use Koard types. When a failure is caught as KoardException, inspect error.errorType using the SDK Error Codes reference. A reader event's statusCode is a separate diagnostic field; it does not provide an errorType property.

For most apps, routing on actionStatus + finalStatus is sufficient. The statusCode is useful for debugging, logging, and handling edge cases like re-enrollment (12) or developer mode (2000).

The status codes fall into several categories by the operation or condition they describe:

Connector Status (92 to 98): Service Binding Failures

These indicate problems communicating between the Koard SDK and the Visa Tap to Pay Ready app installed on the device.

Code Description What to do
92 Failed to bind to the reader service Ensure the Visa Tap to Pay Ready app is installed and up to date
93 Sending a message to the reader service failed Retry the operation; if persistent, restart both apps
94 Reader response payload could not be parsed Update the Visa Tap to Pay Ready app
95 Connector-side serialization/deserialization failed Update the Koard SDK to the latest version
96 Companion app missing on device Use the SDK installation flow to install the Visa Tap to Pay Ready app
97 Google Play Protect / Verify Apps is disabled Enable Play Protect in Google Play settings
98 Another merchant app holds the reader service Close that app or wait for it to finish; resetting your connection cannot release its lock

General Status (10, 21, 62): Environment Readiness

Code Description What to do
10 Network unavailable or SDK request timed out Restore connectivity and reconcile any submitted transaction before retrying
21 Device OS level not supported by Tap to Pay Device must run Android 13 (API 33) or later
62 Visa Tap to Pay Ready app is outdated Update the Visa Tap to Pay Ready app from Google Play

Eligibility Status (80 to 86): Device Capability Checks

These codes identify device hardware or software limitations reported during setup.

Code Description What to do
80 OS flavor/build is unsupported Device uses an incompatible Android build (e.g., custom ROM)
81 Device lacks a hardware-backed keystore Device does not meet security requirements
82 Elliptic-curve crypto APIs missing or disabled Device crypto hardware insufficient
83 AES crypto acceleration unavailable Device crypto hardware insufficient
84 DES crypto unavailable Device crypto hardware insufficient
85 NFC hardware missing or disabled Enable NFC in device settings, or device has no NFC
86 Google Play Services absent or out of date Install or update Google Play Services

Initialize Status (1, 3, 4, 52): Enrollment & Bootstrap

Code Description What to do
1 Device already enrolled for Tap to Pay No action needed: the device is already set up
3 Missing device-auth public key identifier Re-run the enrollment flow
4 Enrolled device identifier not provided Ensure the SDK is configured with a valid merchant profile
52 Random nonce required by enrollment is missing Re-run the enrollment flow

Security Status (1000 to 2003): Device Integrity

Code Description What to do
1000 Emulator detected Tap to Pay cannot run on emulators: use a physical device
1001 Device rooted or superuser binaries present Device must not be rooted
1002 Device tamper detection triggered Device has been modified and is not trusted
2000 Developer options must be disabled Disable developer mode before running transactions
2001 USB debugging/logging must be disabled Turn off USB debugging in developer options
2003 Runtime hook/instrumentation detected Remove any instrumentation frameworks (Frida, Xposed, etc.)

Prepare Status (7 to 91): Pre-Transaction Secure Channel

These codes occur when the SDK starts the reader or prepares for a transaction. They relate to the secure channel between the device and the payment service.

Code Description What to do
7 Reader authentication failed Check API credentials and network connectivity
11 Reader initialization not completed before use Complete SDK initialization before starting transactions
12 enrollDevice() not completed Device needs enrollment; show the enrollment UI and re-enroll. This also occurs if the Visa Tap to Pay Ready app was reinstalled
17 Could not load enrollment/transaction config blobs Re-initialize the SDK
18 Reader authentication service returned an error Transient backend issue; retry
20 Hardware keystore missing when preparing keys Device does not meet security requirements
24 Device attestation failed or invalid Re-enroll the device; ensure Play Protect is enabled
25 Login exchange with payment service failed Check network; retry
26 Login response missing assertion blob Transient backend issue: retry
27 Login response missing crypto payload Transient backend issue: retry
28 Entire login response was null Transient backend issue: retry
29 Login HTTP body empty Transient backend issue: retry
30 Login response missing auth status Transient backend issue: retry
31 Shared secret not derived Re-enroll the device
32 Session keys missing Re-enroll the device
33 MAC/signature mismatch in response Possible tampering: re-enroll the device
34 MAC tag verification failed Possible tampering: re-enroll the device
36 Payment service explicitly rejected authorization Check merchant configuration with Koard support
37 Auth status element empty Transient backend issue: retry
49 Could not fetch key-rotation seed list Check network connectivity
50 TLS pinning check failed Possible man-in-the-middle: check network security
51 Could not derive transaction keys Re-enroll the device

Key Rotation Status (87 to 91)

Code Description What to do
87 Reader requested key rotation SDK handles this automatically; no action needed
88 Key rotation already satisfied (not needed) Informational: no action needed
89 Key rotation completed successfully Informational: no action needed
90 Key rotation failed Re-enroll the device if transactions fail
91 Reader did not return key rotation status Re-enroll the device if transactions fail

Prepare Progress (70 to 75): prepare() Warm-Up

The sdk.prepare() warm-up flow emits KoardPrepareResponse objects whose status is a KoardPrepareStatus. Codes 70 to 75 are the normal lifecycle; anything in the 80 to 199 range is surfaced as KoardPrepareStatus.Error(code), and an unrecognized code becomes KoardPrepareStatus.Unknown(code). These progress codes are informational: wait for Done (or an Error) rather than handling each one.

Code KoardPrepareStatus Meaning
70 Called The reader accepted the prepare() invocation
71 AuthenticationInProgress Authenticating the device against the backend
72 AttestationInProgress Performing Play Integrity / device attestation
73 GettingConfigurations Downloading transaction configurations
74 ParsingConfigurations Parsing the downloaded configurations
75 Done Prepare completed: SDK is ready for transactions
80:199 Error(code) Prepare did not reach Done (auth/attestation failure, key rotation, network error, etc.): retry on the next user action

Transaction Status: In-Progress Codes

These codes appear during an active transaction and are reflected in the readerStatus field:

Code Reader Status Description
109 readyForTap POS state started: reader is waiting for a card tap
112 preparing POS state message: reader is preparing for the transaction
106 readCompleted Card read completed successfully

Generic Failure (-1)

Treat -1 as a generic failure and retain statusCodeDescription when present. For a wrapped exception, see Generic and Unmapped Codes: its type depends on the detail available to the wrapper. A reader event's description is not a stable value to parse for control flow.

Status code 12 (enrollment not done) deserves special handling. The demo app treats statusCode == 12 during OnFailure as retryable (alongside 42, 53, and a null status code); it prompts "Please tap again" rather than surfacing an error. If the code persists, the Visa Tap to Pay Ready app was most likely reinstalled or had its data cleared; the merchant app must then clear its stored enrollment data (clearEnrollmentState()) and re-run enrollDevice(). Re-enrollment is never automatic.

Display Message IDs

During the tap-to-pay flow, the SDK emits display messages via displayMessage on each OnProgress event. These correspond to standard EMV message identifiers from the reader service:

Message ID Description
Approved 03 Authorization obtained: transaction approved
Cancel or Enter 05 Prompt to cancel or confirm
Card Error 06 Unrecoverable card data error
Not Authorized / Declined 07 Transaction was declined by the issuer
Please remove card 10 Card not yet removed from the reader field
Please try again 13 Recoverable error: retry the tap
Welcome 14 Idle state: reader is ready
Present card 15 Prompt the cardholder to tap
Processing 16 Transaction is being processed
Card read OK / Remove card 17 Card was read successfully: may be removed
Please insert or swipe card 18 Contactless not supported: try contact/mag-stripe
Please present one card only 19 Card collision detected: present only one card
Approved. Please Sign 1A Approved; signature required
Authorizing. Please Wait 1B Online authorization in progress
Insert, swipe, or try another card 1C Contactless failed: use another interface or card
Please insert card 1D Chip card should be inserted into the slot
(Empty string) 1E Clear the display
See Phone for instructions 20 Mobile device CVM required (Touch ID, Face ID, etc.)
Present card again 21 Recoverable error: present the card again
Practice Mode 40 Successful test/practice transaction
Partial Approval 43 Issuer approved a lesser amount
Cancelled for Device Security 46 Transaction cancelled due to a device security issue
Cancelled 47 Generic transaction cancellation
Try another card - No contact interface 48 Card returned GPO error (SW 6984): transaction aborted
Strong CVM 49 SCA issuer response requires interface switch: transaction declined

Abort and Error Scenarios

The SDK returns an Abort or Failure final status in several well-defined situations. Understanding these helps you build robust error handling:

Transaction Abort Scenarios

Scenario What Happens Message ID
User cancels PIN entry User selects "Cancel Transaction" on the PIN keypad None
PIN session timeout 1 minute of inactivity on the PIN keypad None
PIN keypad interrupted Another app covers the PIN screen None
Network loss during PIN Network drops before the PIN event is sent None
Split screen mode Device enters split screen while on PIN screen: sends CVEntrySecurity cancel None
Device security issue Security configuration problem detected 46
Generic cancellation User or system cancelled the transaction 47
Card NFC failure (GPO 6984) Card cannot complete contactless: abort with MACompletion indicator 48
Strong CVM / SCA switch Issuer requires contact interface (not supported): decline with MACompletion 49
Developer mode enabled Developer options are on: reader blocks the transaction None

OnFailure Status Codes

When actionStatus is OnFailure, check statusCode for the specific reason:

Status Code Constant Description
TRANSACTION_WINDOW_FOCUS_CHANGED The transaction window lost focus (another app came to foreground)
CAMERA_IS_ACTIVE Device camera is active: conflicts with the secure NFC session
DEVELOPER_MODE_ENABLED Developer options are enabled on the device
NFC_NOT_AVAILABLE Device NFC is disabled or unavailable
DEVICE_NOT_ENROLLED Device has not completed enrollment
SESSION_TIMEOUT The transaction session timed out

Developer Mode: The most common cause of unexpected transaction failures during development. Always disable developer mode before running transactions. Follow the workflow: Enable dev mode → Install app → Disable dev mode → Run transactions.

Completion Indicators

The receipt field emv.tx.tm.CompletionIndicator tells you how the transaction concluded at the reader service level:

Value Meaning
FullCompletion Transaction completed normally through the full authorization flow
MACompletion Transaction was terminated by the reader service (Merchant Application completion); typically an abort or forced decline

Handling Responses in Practice

The SDK uses two error channels. Here is a complete pattern for handling both:

Channel 1: Transaction Flow (KoardTransactionResponse)

For sale(), preauth(), completePartialAuth(), and tap-based refunds, use the complete reader response handler in Running Payments. Keep collecting the same flow for retryable read hints with no final status; do not start another payment. Classify completion by the returned transaction status as well as the nullable finalStatus, handling partial approval and surcharge decisions before a completed receipt. A flow that ends without a terminal event needs outcome recovery.

Channel 2: API & SDK Operations (KoardException)

See SDK Error Codes for typed exception handling, Result failures, and cancellation. Keep SDK calls on a worker thread and UI updates on Main. Reconcile a submitted operation after an uncertain response instead of automatically replaying it.

Next Steps

  • Review the Running Payments guide for the complete payment flow implementation
  • See the Demo App for a working example of response handling in MainScreenViewModel
  • Consult the API Response Codes for HTTP-level status codes from the Koard REST API