Error handling
Presentation
Errors in the mobile SDK are returned through the LyraException object which has the following parameters:
| Parameter | Description |
|---|---|
| errorCode | It allows you to identify the current error (in [PREFIX]_[CODE] format). |
| errorMessage | Explains the error corresponding to the code. |
| detailedErrorCode | Code of the underlying error causing the exception (or null). |
| detailedErrorMessage | Message of the underlying error (or null). |
The detailedError field indicates the exact cause of the error to help you identify the issue.
Error types
Errors that occur during development must be differentiated from those that may occur during the execution of the SDK.
Development errors
In this case, the SDK will throw an exception of type LyraException. It must be captured by the developer.
Here are the cases when this can happen.
After calling the method initialize():
If the publicKey parameter format is incorrect, an Exception MOBP_001-INVALID_KEY will be thrown.
If the apiServerName parameter format is incorrect, an Exception MOBP_012-UNKNOWN_API_SERVER_NAME will be raised.
After process() method call :
- If the SDK has not been initialized beforehand, a MOBP-002-INITIALIZATION_REQUIRED exception will be raised.
Runtime errors
For other errors, the information will be transmitted in the LyraException object via the callback function onError(), as described in the integration guide.
Error codes
An error code takes the [PREFIX]_[CODE] format where:
| [PREFIX] | Defines the application layer where the error occurred. |
| [CODE] | Numeric error code. |
There are different prefixes:
| PREFIX | Description | EXAMPLE OF AN ERROR |
|---|---|---|
| MOB | Mobile SDK error | MOB_004 |
| ACQ | Error on the acquirer side | ACQ_001 |
| AUTH | Authentication error | AUTH_149 |
| INT | Integration error (on the merchant side) | INT_007 |
| PSP | Error on the payment gateway side | PSP_001 |
Beware, new error codes may be added in the future (even if you don't update your SDK and your mobile application). Your implementation must therefore take this into account, and integrate a generic error handling algorithm.
ACQ, AUTH, INT and PSP errors
These error codes concern communications with the payment servers (to the payment platform, your merchant server, etc...). Please see Error Codes for details of this type of error.
Error handling recommendation
Whatever the case of error, we recommend that you always display a message to the user to inform them that the payment did not take place. We recommend that you keep track of the errorCode, detailedErrorCode and their associated messages so that you can analyze the incidents you may encounter and resolve them independently. In case of an error, you should NEVER assume that the payment has been made.
MOB errors
These errors appear if an error occurs on the mobile SDK side.
| ERROR CODE | Definition |
|---|---|
| MOB_001 | Invalid public key |
| MOB_002 | SDK initialization is required before calling the process |
| MOB_003 | Invalid formToken |
| MOB_004 | Invalid formToken version |
| MOB_005 | Impossible to communicate with server |
| MOB_006 | Network is not available |
| MOB_007 | Invalid response of Lyra Rest API |
| MOB_008 | Payment refused |
| MOB_009 | Payment cancelled |
| MOB_010 | Server timeout error, check IPN |
| MOB_011 | Unknown API Server Name |
| MOB_012 | Unknown Order Status |
| MOB_013 | Payment cannot be cancelled |
| MOB_999 | Unexpected error |
Error code details
MOB_001
| Code | MOB_001 |
| DEFINITION | Invalid public key |
The public key provided upon SDK initialization is not correct. You may be trying to perform a test transaction with a production key or vice versa. Please see Prerequisites
MOB_002
| Code | MOB_002 |
| DEFINITION | SDK initialization is required before calling the process |
You are attempting to call the process method before you have called the init method. Refer to the Android integration guide and IOS integration guide on SDK initialization.
MOB_003
| Code | MOB_003 |
| DEFINITION | Invalid formToken |
The form identifier does not appear to be correct. Make sure you have followed the instructions in the integration guides. If there is nothing that would cause an error, call support*.
MOB_004
| Code | MOB_004 |
| DEFINITION | Invalid formToken version |
The version of the form id is not right. To make sure you have the right version, call the SDK's getFormTokenVersion method and pass the results in the formTokenVersion parameter of the createPayment.
MOB_005
| Code | MOB_005 |
| DEFINITION | Impossible to communicate with server |
Please contact the support team*.
MOB_006
| Code | MOB_006 |
| DEFINITION | Network is not available |
The device does not seem to be connected to the internet. A message to the user to make sure it is connected may be helpful in this case.
MOB_007
| Code | MOB_007 |
| DEFINITION | Invalid response of Lyra Rest API |
Please contact the support team*.
MOB_008
| Code | MOB_008 |
| DEFINITION | Payment refused |
The payment was refused after the retry count was reached.
MOB_009
| Code | MOB_009 |
| DEFINITION | Payment cancelled |
The payment has been voluntarily canceled. The buyer voluntarily left the payment screen or the Lyra.cancelProcess() was called.
MOB_010
| Code | MOB_010 |
| DEFINITION | Server timeout error, check IPN |
The payment server did not respond within 60 seconds. This may simply be due to a time slowdown, so it is strongly advised to check the IPN notification afterwards, and cancel the transaction to maintain consistency.
MOB_011
| Code | MOB_011 |
| DEFINITION | Unknown API Server Name |
The value sent in the apiServerName field is not recognized, probably due to a typing error.
MOB_012
| Code | MOB_012 |
| DEFINITION | Unknown Order Status |
This error is raised if the payment gateway returns a payment status that is different from RUNNING, PAID, PARTIALLY_PAID or UNPAID.
MOB_013
| Code | MOB_013 |
| DEFINITION | Payment cannot be cancelled |
The payment cannot be canceled after a call to Lyra.cancelProcess().
MOB_999
| Code | MOB_999 |
| DEFINITION | Unexpected error |
An unexpected error has occurred. Please contact the support team.
When you contact support, please communicate:
- Your 8-digit shop number
- The OS and SDK version
- Device used (iPhone 6S, PC, iPad Pro, etc.)
- The OS version
- Error date and time
- The errorCode and detailedErrorCode that you encounter (if applicable)
All this information will shorten the time it takes to analyze and understand your problem.
