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 |
Note that new error codes may be added in the future (even if you do not update your SDK and mobile application). Thus, your implementation must take this into account, and integrate a generic error handling algorithm.
ACQ, AUTH, INT and PSP errors
These error codes concern the communication with the payment servers (to the payment gateway, your merchant server, etc.). Please see Error codes for information on this type of error.
Error handling recommendation
Regardless of the error case, we recommend that you always display a message to the user to inform them that the payment has not occurred. We advise you to trace the errorCode, the detailedErrorCode and their associated messages in order to be able to analyze the issues you may encounter and resolve them on your own. In the event 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_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 attempt to call the process method before calling the init method. See the Android Integration Guide and the iOS Integration Guide on SDK initialization.
MOB_003
| Code | MOB_003 |
| Definition | Invalid formToken |
The form identifier appears to be incorrect. Make sure you have followed the instructions provided in the integration guides. If you do not see a possible error cause, call tech support*.
MOB_004
| Code | MOB_004 |
| Definition | Invalid formToken version |
The version of the form identifier is not good. To make sure you have the correct version, call the getFormTokenVersion method of the SDK and pass the results in the formTokenVersion parameter of 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 appear to be connected to the Internet. In this case, it can be useful to send a message to the user to make sure he or she is logged in.
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 was abandoned by the buyer. The buyer has voluntarily left the payment screen.
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 temporary slowdown. Therefore, it is strongly advised to check the IPN afterwards, and cancel the transaction to keep 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_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.
