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

