When integrating with the SDK, you may encounter two distinct types of failures. Understanding the difference between them is essential for correct error handling.
| Scenario | Trigger | How to Detect | Result Availability |
|---|---|---|---|
| 1. Technical Execution Failure | Request fails before or during processing | onError callback is triggered | No valid transaction result |
| 2. Business Transaction Failure | Request reaches host but is declined | response = FAIL / PART in result | Transaction result returned with details |
The onError callback is triggered when a request fails due to technical reasons before a valid transaction result can be produced:
When onError is triggered, no transaction result is returned. The request did not reach the host or failed during transmission.
| Code | Description |
|---|---|
| -1001 | Request rejected by the target system. |
| -1002 | No matching response found for the request. |
| Code | Description |
|---|---|
| -1003 | Permission denied. Bluetooth permission required (e.g., BLUETOOTH_CONNECT). |
| -1004 | LAN communication parameters not configured. |
| -500 | Bluetooth MAC address connection failed or timed out. |
| Code | Description |
|---|---|
| -99 | Unsupported LAN communication protocol. |
| -100 | Inter-process communication failed. |
| -101 | Required service not available. |
| Code | Description |
|---|---|
| -200 | Failed to establish HTTP connection. |
| -201 | Invalid or failed HTTP response. |
| -300 | RSocket I/O error occurred. |
| Code | Description |
|---|---|
| -400 | Unsupported message format or mapper. |
| -401 | Required fields are missing. |
| -402 | Request message validation failed. |
| -403 | Response validation failed. |
| -404 | Missing required service-specific data. |
When a request is successfully transmitted and processed by the host, but the transaction itself is declined or partially approved, the SDK returns a transaction result (e.g., PaymentResult, RefundResult) with the response field set to FAIL or PART.
In this scenario:
The response field indicates the overall outcome of the transaction:
| Code | Meaning | Action Required |
|---|---|---|
| SUCC | Success. Transaction approved. | Proceed with business logic. |
| FAIL | Failure. Transaction declined. | Check responseReason for details. |
| PART | Partially approved. | Check responseReason; host approved a smaller amount. |
When response is FAIL or PART, the responseReason field provides detailed failure information:
| Code | Meaning | Typical Cause |
|---|---|---|
| ABRT | Aborted | The initiator sent an abort request. |
| BUSY | Busy | System is temporarily overloaded; retry later. |
| CANC | Cancelled | User cancelled on the terminal (e.g., during PIN entry). |
| DEVO | Device Out of Order | Terminal hardware malfunction. |
| NHOS | Unreachable Host | Acquirer or host did not respond; may retry. |
| REFU | Refusal | Host or local rules declined the transaction. |
| TNFD | Not Found | Original transaction not found (reversal/repeat). |
| UNVD | Unavailable Device | Required hardware not present or not configured. |
| UNVS | Unavailable Service | Service not implemented or protocol too old. |
| WIPG | In Progress | Transaction is still processing; command rejected. |
| WPIN | Wrong PIN | PIN verification failed on the terminal. |
| Check Point | Condition | What It Means | Next Step |
|---|---|---|---|
| Step 1 | Was onError triggered? | Technical failure | Handle using onError codes above |
| Step 2 | Is result.response = FAIL? | Business decline | Check responseReason for cause |
| Step 3 | Is result.response = PART? | Partial approval | Host approved a smaller amount; check authorisedAmount |
| Step 4 | Is result.response = SUCC? | Full success | Transaction completed normally |
