Understanding the SDK


In this page we cover a few explanations over our solution which intent to help you to understand better the elements you are using in your solution.

Solution Core Elements

Here we can see the core physical elements for the Mobile Payment Solution:

  • POS APPLICATION: represents the POS solution, developed and installed on a physical device, which is going to communicate with the SDK in its own platform (platform plugin) language to use diferent payment devices (device plugin) to read cards data and communicate with the payment gateway (gateway connector) to process diferent types of transactions.
  • PAYMENT DEVICE: element that enables the POS to read cards' data using the certified industry standarts. Each Payment device has its own libs (libraries to integrate) and the SDK integrates them into the POS solution using the devices' plugins. The SDK already has a large set of market payment devices' plugins implemented, acquirer certified and available to use, and it's always expanding - contact our sales team to know the news about devices.
  • PAYMENT GATEWAY: main business component of the whole solution. Responsible for processing the transactions requested by the POS solution. This component is going to execute the business rules, the communication with acquirers and other gateways, and finally, the mantainance of business data.



General Solution Flows

Depending on the transaction type (sale, refund, consults, etc.), different flows are generated involving these three elements and its ‘interfaces’.

To make the SDK a simple and efficient experience for development, our architecture simplifies the communication, generating shorter flows where each request generates a callback for success or failure, abstracting the communication with the card reader devices.

The following diagrams represent different scenarios which may be applicable to your solution.

Keyed Transactions

  • No card reader device.
  • Card data is entered manually by an user.
  • Doesn't require or use device plugins.



EMV Transactions

  • Uses a card reader device.
  • Card data is captured by the card reader device and communicated to the POS App by the SDK encrypted to be sent to the gateway, all of that transparently to the POS.
  • Require the installation of the device plugin.
  • Used for Chip Cards.



MSR/Swipe Transactions

  • Uses a card reader device.
  • Card data is captured by the card reader device and communicated to the POS App by the SDK encrypted to be sent to the gateway, all of that transparently to the POS.
  • Require the installation of the device plugin.
  • Used for Magnetic Striped Cards.



Detailed Solution Flows

Depending on the solution you intend to implement, different flows need to be implemented.

The next diagrams show a more detailed interaction, closer to the implementation your application is going to reproduce in order to execute transactions - the example is based on a simple sale scenario.

Keyed Transactions



EMV Transactions



MSR/Swipe Transactions


Error List Guide

Below you can see a summary of the errors that might be returned by the SDK.


ERROR TYPE ERROR CODE DESCRIPTION REASON
CoreError ERROR_UNKNOWN Unknown error has occurred. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError ERROR_AUTHENTICATION_TOKEN Authentication error, the token used for secure authentication is invalid. Authentication token was not sent.
Authentication token is incorrect.
Authentication token does not exist.
CoreError ERROR_CURRENCY_NOT_SUPPORTED Currency is not supported by the terminal. The terminal being used is not configured for the currency provided. Check the currency in terminal settings.
CoreError ERROR_TRANSACTION Error during transaction. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError ERROR_SERVER Error communicating with server. Connectivity issues. Try to check the host configured for the app, the connection status with the internet, the connection status with the gateway server, then try to connect to the server again.
CoreError ERROR_TIMEOUT Timeout has occurred while waiting for the response. Connectivity issues. Try to check the host configured for the app, the connection status with the internet, the connection status with the gateway server, then try to connect to the server again.
CoreError ERROR_NETWORK Network error, problem with connectivity. Connectivity issues. Try to check the host configured for the app, the connection status with the internet, the connection status with the gateway server, then try to connect to the server again.
CoreError VALIDATION_ERROR Invalid Core Object settings. The data sent is incorrect for some reason. Check the format and values.
CoreError ERROR_JSON Error parsing JSON, only if there is an invalid response from the server. The terminal in use might not be completely configured for use yet. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError INCORRECT_SETTINGS_TERMINAL Terminal ID is incorrect. A terminal (number) that shouldn't be used or does not exist was provided when initializing the terminal.
CoreError INCORRECT_SETTINGS_SECRET Secret is incorrect. The password provided for the terminal (number) informed is incorrect.
CoreError INCORRECT_SETTINGS Settings contain incorrect values. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError ERROR_SIGNATURE_NULL Signature data is null. Signature is necessary, but it was not provided.
CoreError ERROR_ORDER_ALREADY_PROCESSED Order has already been processed The order id provided was already used before and the order Id must be unique.
CoreError SETTINGS_MISSING This error is thrown when required settings are missing. The terminal in use might not be completely configured for use yet. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError ERROR_CONNECTION Occurs when the SDK cannot connect to the host. Connectivity issues. Try to check the host configured for the app, the connection status with the internet, the connection status with the gateway server, then try to connect to the server again.
CoreError TERMINAL_DOES_NOT_ALLOW_CHP Occurs when terminal does not allow cardholder present transactions. Check the transaction information. You might have sent CHP data and your terminal does not have this feature enabled.
CoreError DECRYPTION_FAILED_DEVICE_NOT_REGISTERED Device is not registered on the server, transaction won’t be processed. Check if the device is registered.
CoreError CANT_REFUND_TRANSACTION Transaction can’t be refunded. Possibly the transaction was already voided so it can't be refunded anymore.
CoreError SELFTEST_MODE_NOT_SET SelfTest mode is not set in Terminal. Configuration issue. Your terminal should be set in Test mode for some reason, and it's not.
CoreError RESOURCE_FILE_WITH_COREPAY_URL_NOT_FOUND payconfig.xml file doesn’t exists. Check your application. It's missing an important configuration file.
CoreError INVALID_REFUND_AMOUNT This error occurs when Refund amount is too low or negative. The refund amount is not acceptable.
CoreError UNREFERENCED_REFUND_SHOULD_BE_ENABLED Unreferenced Refunds are not enabled on the terminal in Selfcare system. Check the transaction information. You might have sent unreferenced refund data and your terminal does not have this feature enabled.
CoreError VALIDATION_LIMIT_REACHED Validation limit reached. Lots of requests to the server are performed in small amount of time. Your terminal account has a set of limits which can be configured to provide better security. This error indicates that one of those configured limits was reached.
CoreError TAX_AMOUNT_MUST_BE_GREATER_THAN_ZERO This error occurs when Tax amount is too low. Some transactions, depending on your terminal account (acqurier and other rules), might require the definition of a tax amount value, or even just because the transaction needs to provided this information. In these cases, the value can't be negative or zero - as the error code states.
CoreError USER_DOESNT_HAVE_ASSOCIATED_PRIVILEGE User doesn’t have privilege to view Open/ Closed batch transactions. Permission issue. This option needs to be enabled in Selfcare system.
CoreError TIP_AMOUNT_MUST_BE_GREATER_THAN_ZERO This error occurs when Tip amount is too low. Some transactions might need to provide a tip amount value, that can't be negative or zero - as the error code states.
CoreError ORDER_ID_WRONG_LENGTH The length of the order id must be between 3 -24 characters. The data provided has a length constraint.
CoreError ERROR_GENERAL_COUNTRY_UNKNOWN Unknown country. The country provided does not exist. It might be misspelled or refers to a inexistent country.
CoreError ERROR_DIGEST_MISMATCH Digest mismatch. Request was unsuccessful. The digest sent is inconsistent with what was expected, and the reason might be:
- No digest sent.
- Digest structure, sequence and values do not match the expected.
- Incorrect/ Unsupported encoding.
- Incorrect/ Unsupported algorithm used to create the digest.

Contact us for further investigation.
CoreError ERROR_INVALID_API_KEY API key is invalid. Contact us and request to verify:
- If the API key sent on request is correct.
- If the API key sent on request is still valid.
CoreError ERROR_INVALID_AUTHENTICATION_TOKEN Authentication error, the token used for secure authentication is invalid. Contact us and request to verify:
- If the authentication-token was sent on request.
- If the authentication-token sent on request is a valid one.
CoreError ERROR_INVALID_USER_ACCESS Invalid user access. The user has one of the following issues:
- It does not exist, it's not active or it has used incorrect credentials.
- It has no permission to the terminal/ merchant informed.
- It has no permission to the feature requested.
- It has an expired password/ change request pending
CoreError ERROR_METHOD_NOT_SUPPORTED Method not supported. Verify if the settings on your terminal account match what you are requesting.
If that is not the source of the issue, contact us and ask to verify the request details against the terminal settings.
CoreError ERROR_VALIDATION_LIMIT_HIT Validation limit hit. Too many requests performed in a short amount of time. Try again in a few seconds or contact us for further investigation.
CoreError ERROR_SWIPE_WITHOUT_FALLBACK_NOT_ALLOWED Swipe without fallback is not allowed. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError ERROR_INVALID_EMV_TAGS Invalid EMV tags. Decryption on the server has failed. Usually occurs when device’s KSN is not registered on the server.
CoreError ERROR_INVALID_TRACK_DATA Invalid track data. Decryption on the server has failed. Usually occurs when device’s KSN is not registered on the server.
CoreError ERROR_INVALID_APPLE_PAYLOAD Apple payload has invalid data. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError ERROR_INVALID_AMOUNT Amount is Invalid. The amount provided for the transaction is invalid for some reason (format, too big, too small, etc.). Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError ERROR_INVALID_CURRENCY Currency is not supported by the terminal. The terminal being used is not configured for the currency provided. Check the currency in terminal settings.
CoreError ERROR_GENERAL General error. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError ERROR_INVALID_ARGUMENT Invalid argument. Request was unsuccessful. This error might have many different origins, but usually is related to inconsistent data. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError INVALID_MERCHANT_REFERENCE Merchant reference is invalid. A merchant reference sent is inconsistency (format or value). Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError ERROR_INVALID_URL Invalid URL. Usually occurs when payconfig.xml file is not properly configured. Error in configuration file (URL incorrect or the format is not valid).
CoreError DEVICE_NOT_CONNECTED Device is not connected. Trying to use a device without connecting first, or after losing connection.
CoreError DEVICE_CANNOT_BE_NULL Device is null. When passing null instead of any of the DeviceEnum values. No providing an acceptable Device (using one of DeviceEnum values).
CoreError CARD_CVV_WRONG_FORMAT_OR_LENGTH Wrong CVV format or length. CVV provided has a incorrect format. CVV should be between 3-4 numeric digits.
CoreError CARRIAGE_RETURN_FOUND Carriage return found during CoreSale field validation. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreError TERMINAL_OFFLINE_INPUT_METHOD_NOT_SUPPORTED Terminal is offline. Input method is not supported. Using an input method that is not acceptable when the terminal is operating on offline mode.
CoreError INCORRECT_CHECKER_TIMEOUT_OR_INTERVAL Incorrect checker timeout or interval. Provided a incorrect/ unacceptable value as timeout configuration for the Terminal Offline Mode Healthy Checker option.
CoreError CHECKER_NOT_STARTED_OR_TERMINAL_MANUALLY_SET_TO_OFFLINE Checker not started or terminal was manually set to offline mode. You must start the checker.
CoreError TERMINAL_IS_OFFLINE Terminal is on offline mode. An operation is attempted in offline mode and is not allowed on it.
CoreError POLLING_NOT_SUPPORTED Polling is not supported. Trying to use the polling mode when not supported/ configured.
CoreError MANUAL_ENTRY_CURRENTLY_NOT_SUPPORTED Manual entry transactions are not supported. Trying to use Keyed transactions when not allowed by the terminal configurations. Check the terminal settings or contact us for further investigation.
CoreError ERROR_INVALID_KSN_RANGE Decryption on the server has failed. The KSN range does not exist.
CoreError ERROR_DEVICE_NOT_FOUND Decryption on the server has failed. Device not found in decryptx.
CoreError ERROR_DEVICE_NOT_ACTIVATED Decryption on the server has failed. Device is not activated in decryptx.
CoreError ERROR_ORDER_ALREADY_IN_PROGRESS Order is already in progress. Trying to perform an action that can't be performed on a transaction which is already progress.
CoreDeviceError UNKNOWN Unknown error has occurred. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreDeviceError INVALID_CARD The inserted card is invalid. Something is wrong with the card used.
CoreDeviceError ERROR_DEVICE_NOT_SUPPORTED SDK doesn’t support selected device. Trying to use a device that the SDK does not support. The plugins installed in your application (SDK version) are not able to communicate with the device. If you are using a device that should be supported (as specified in the documentation) contact us for further investigation.
CoreDeviceError TRANSACTION_CANCELLED Transaction was cancelled. Usually when calling cancelTransaction method or cancelling the transaction on the device.
CoreDeviceError TRANSACTION_ERROR Transaction error has occurred. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreDeviceError DEVICE_CONNECTION_ERROR Problem connecting to a device. Most likely a hardware issue. Try again.
CoreDeviceError SWIPE_FAILED Swipe has failed. Please retry. Most likely a hardware issue. Try again.
CoreDeviceError CMD_NOT_AVAILABLE The API or Firmware does not support the command. Most likely a hardware issue. Check documentation.
CoreDeviceError TIMEOUT The device has timed out. Try to connect again.
CoreDeviceError DEVICE_RESET Device was reset. Restart the operation.
CoreDeviceError DEVICE_BUSY Will be triggered when the device receive an inappropriate command. Most likely a hardware issue. Check documentation.
CoreDeviceError INPUT_OUT_OF_RANGE Invalid data value range. Check data values provided.
CoreDeviceError INPUT_INVALID_FORMAT Input has invalid format. Check data values provided.
CoreDeviceError INPUT_ZERO_VALUES Zero value input. Check data values provided.
CoreDeviceError INPUT_INVALID Invalid input. Check data values provided.
CoreDeviceError CASHBACK_NOT_SUPPORTED Will be triggered when the selected transaction type do not accept cashback. Improper action.
CoreDeviceError CRC_ERROR Device communication error. Possible causes:
- mPOS is out of battery.
- Audio jack is defective.
- No response from mPOS.
CoreDeviceError COMM_ERROR Device communication error. Possible causes:
- mPOS is out of battery.
- Audio jack is defective.
- No response from mPOS.
CoreDeviceError FAIL_TO_START_BTV2 Failed to start Bluetooth 2 functions. Restart the device. For further investigation, contact us.
CoreDeviceError FAIL_TO_START_BTV4 Failed to start Bluetooth 4 functions. Restart the device. For further investigation, contact us.
CoreDeviceError FAIL_TO_START_BT Failed to start Bluetooth functions. Restart the device. For further investigation, contact us.
CoreDeviceError VOLUME_WARNING_NOT_ACCEPTED Volume warning not accepted. Restart the device. For further investigation, contact us.
CoreDeviceError FAIL_TO_START_AUDIO Audio couldn’t be started. Restart the device. For further investigation, contact us.
CoreDeviceError INVALID_FUNCTION_IN_CURRENT_MODE The API function is not available in current connection mode. For further investigation, contact us.
CoreDeviceError INVALID_FUNCTION_IN_CURRENT_CONNECTION_MODE The API function is not available in current connection mode. For further investigation, contact us.
CoreDeviceError COMM_LINK_UNINITIALIZED Communication link is uninitialized. Restart the device. For further investigation, contact us.
CoreDeviceError BTV2_ALREADY_STARTED Bluetooth 2 already started. No need for this action.
CoreDeviceError BTV4_ALREADY_STARTED Bluetooth 4 already started. No need for this action.
CoreDeviceError BTV4_NOT_SUPPORTED The Android device has no BLE support. Incorrect use of device.
CoreDeviceError FAIL_TO_START_SERIAL Failed to start serial functions. For further investigation, contact us.
CoreDeviceError INVALID_CARD The EMV card is invalid. Something is wrong with the card used.
CoreDeviceError INTERRUPTED Transaction was interrupted. Another event interrupted the processing of the transaction.
CoreDeviceError WRONG_DEVICE Expects another device to be connected. For further investigation, contact us.
CoreDeviceError TRANSACTION_ABORTED Transaction has been aborted. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreDeviceError TRANSACTION_DENIED Transaction has been denied. The transaction was not accepted by the device.
CoreDeviceError UNSUPPORTED_CARD_TYPE Card type is not supported. The device does not support the card type used.
CoreDeviceError INPUT_OFFLINE_PIN_ONLY Offline pin only. The transaction only accepts offline pin.
CoreDeviceError MAC_ERROR Mac Error. General error on Mac platform.
CoreDeviceError CMD_TIMEOUT Command timeout Error. Communication between POS and device reached timeout. Restart the transaction.
CoreDeviceError WR_DATA_ERROR Data error. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreDeviceError EMV_APP_CFG_ERROR EMV Application Error. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreDeviceError EMV_CAPK_CFG_ERROR EMV Certification Authority Public Key Error. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreDeviceError APDU_ERROE APDU Error. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreDeviceError TAP_FAILED Tap has failed. Action didn't work. Retry.
CoreDeviceError PIN_FAILED Wrong pin entered. Pin provided is not valid.
CoreDeviceError TERMINATED Transaction was terminated. Contact us for further investigation.
CoreDeviceError DECLINED Transaction was declined. -
CoreDeviceError CANCEL Transaction was cancelled. -
CoreDeviceError CAPK_FAIL CAPK has failed. Contact us for further investigation.
CoreDeviceError NOT_ICC The card is not an ICC card. The device was expecting a ICC card but another type was used.
CoreDeviceError SELECT_APK_FAIL Application selection has failed. Contact us for further investigation.
CoreDeviceError APPLICATION_BLOCKED Application is blocked. Contact us for further investigation.
CoreDeviceError ICC_CARD_REMOVED Card has been removed. Card removed before the end of processing.
CoreDeviceError CARD_BLOCKED Card is blocked. -
CoreDeviceError CARD_NOT_SUPPORTED Card is not supported. Card type is not supported by the device used.
CoreDeviceError CONDITION_NOT_SATISFIED Condition is not satisfied. Contact us for further investigation.
CoreDeviceError INVALID_ICC_DATA ICC data is invalid. Something went wrong with the ICC Card data.
CoreDeviceError MISSING_MANDATORY_DATA Mandatory data missing. Check the data sent. Contact us for further investigation.
CoreDeviceError NO_EMV_APPS Empty candidate list or card is not personalized. Contact us for further investigation.
CoreDeviceError NETWORK_NOT_AVAILABLE Network is not available. Connectivity issues. Try to check the connection with the device and try again.
CoreDeviceError TEST_NOT_SUPPORTED_BY_DEVICE Selftest mode. Test is not supported by this device. Use of test mode with device that does not support it.
CoreDeviceError VALIDATION_FAILED_TESTS_NOT_COMPLETED Selftest mode. Validation has failed. Test is not completed. Test failure.
CoreDeviceError CANNOT_INITIALIZE Cannot initialize the device. Problems when initializing the device. Check the data sent and the connection. Contact us for further investigation.
CoreDeviceError AUTO_CONFIG_ERROR Auto configuration error has occurred. Problems when configuring the device. Check the data sent and the connection. Contact us for further investigation.
CoreDeviceError DATA_PARSING_ERROR Data parsing error has occurred. Something compromised the data when parsed. Further investigation is required.
Contact the Gateway's support team with the details of the operation which resulted in this error (including your application's logs, if existing).
CoreDeviceError INVALID_CARD_PLEASE_TRY_AGAIN The card is invalid. Please retry. Change the card used for a valid one and try again.
CoreDeviceError INPUT_METHOD_NOT_SUPPORTED Input method is not supported. Use of input method with inappropriate device.
CoreDeviceError INPUT_METHOD_NOT_SUPPORTED_FOR_DELAYED_AUTH Input method is not supported for delayed AUTH. Use of inappropriate input method with delayed auth mode.
CoreDeviceError CORE_TRANSACTION_INPUT_METHOD_NOT_SUPPORTED Input method is not supported. Use of not support input method.
CoreDeviceError GIFT_CARD_ENCRYPTION_ENABLED Gift card encryption is not enabled. Contact us for further investigation.
CoreDeviceError ENCRYPTION_NOT_ENABLED Card encryption is not enabled. Contact us for further investigation.
CoreDeviceError PLUGIN_CANNOT_BE_INITIALIZED_EMV_SETTINGS_MISSING Emv settings are missing. Plugin cannot be initialized. Contact us for further investigation.
CoreDeviceError TRANSACTION_CANNOT_BE_CANCELED_AT_THIS_STAGE Transaction cannot be cancelled at this stage. Trying to cancel a transaction that can't be cancelled anymore.
CoreDeviceError FIRMWARE_FILE_NOT_VALID Firmware file is not valid during firmware update on ingenico devices. Contact us for further investigation.
CoreDeviceError ERROR_OCCURRED_DURING_LOADING Error occurred during ingenico OTA loading. Contact us for further investigation.
CoreDeviceError CONFIGURATION_FILE_NOT_VALID Configuration file is not valid during configuration update on ingenico devices. Make sure the file path is correct.
CoreDeviceError RKI_FILE_NOT_VALID RKI file is not valid during RKI update on ingenico devices. Make sure the file path is correct.
CoreDeviceError ASSET_FILE_NOT_VALID Asset file is not valid during asset update on ingenico devices. Make sure the file path is correct.
CoreDeviceError EMV_TAGS_NOT_FOUND EMV tags are missing from the device. Contact us for further investigation.
CoreDeviceError SERV_NOT_ALLOWED This feature is currently disabled. Trying to use a feature that is not enabled.
CoreDeviceError TIPS_NOT_ENABLED_ON_THE_SERVER Tips needs to be enabled on the server. Check your account and enabled/ add tips before using them (if you have access to the feature).
CoreDeviceError TIPS_BY_PERCENTAGE_NOT_ENABLED_ON_THE_SERVER Tips by percentage needs to be enabled in the Selfcare system. Feature is not enabled. Contact us for further investigation.
CoreDeviceError TIPS_BY_AMOUNT_NOT_ENABLED_ON_THE_SERVER Tips by amount needs to be enabled in the Selfcare system. Feature is not enabled. Contact us for further investigation.
CoreDeviceError FORM_ERROR There is a problem with ingenico form. Contact us for further investigation.
CoreDeviceError CUSTOM_TIP_ERROR Custom tip couldn't be added. There is a problem with ingenico form. Contact us for further investigation.