The SDK requires minimum java version 1.7.
The SDK requires minimum Android version 5.
The SDK requires minimum IOS version 9.1.
The SDK requires minimum version 16.04.
The SDK requires minimum .NET C# version 4.5.1.
When downloading our SDK there is also an option to download our latest sample application along with it. Our sample application can be a good foundation for your integration as you can view the code to see how certain functions are expected to work. This can also be useful for comparing to your application and troubleshooting.
As part of the cardholder verification method some cards require signature to be collected. The SDK gives you 2 options to choose from.
sale.setSignatureCollection(SignatureCollection.AUTOMATIC);
sale.setSignatureCollection(SignatureCollection. MANUAL);
A - Approval Transaction was approved.D - Declined Transaction was declined.C - Pick Up Transaction was declined. This type of decline means that the card has been marked as lost or stolen by the cardholder.R - Referral Transaction was declined. A referral means that the merchant should call the authorization center because more information is needed regarding the cardholder.When a transaction is approved, the response code of A is returned. Your solution NEEDS TO VERIFY THE RESPONSE CODE before continuing. Receiving any response doesn't indicate that the transaction was approved. For the transaction to be approved, the response code must be A.
On a First Data terminal, transactions below $100.00 will receive an Approved response.
Transactions in the amount of $45.67 will receive No Host Response to simulate Time-out Reversal testing.
Transactions above $100.00 will receive a specific Error response (last three digits of amount, despite the decimal separator).
E.g., for the amount $101.23 response code 123 will be returned
On a TSYS Sierra terminal, the following cent values will trigger different responses:
| CENT VALUE | RESPONSE |
|---|---|
| 0.01 | Declined |
| 0.02 | Referral |
| 0.03 | CVV failure (Decline) |
| Any other | Authorised |
An American Express card and a value of $10.00 will trigger a timeout response.
Input method allows you to configure how a card is read using the device readers.
The following input methods are supported and should be self explanatory:
You can choose the input method you would like to use for your integration by setting the following SALE object property.
Eg. sale.setTransactionInputMethod(CoreTransactionInputMethod.SWIPE_OR_INSERT_OR_TAP_OR_KEYED);
Stored value cards are also referred as Gift cards. Unlike other bank cards where the monetary value is stored in a bank account, for gift cards monetary value is stored in the card itself.
Currently we don't support processing the gift card payments through our gateway however we will be able to send the gift card data to the merchant for them to process locally on their system for Ingenico devices. To use this option the merchants have to share the bin ranges of their gift cards to our integrations team and they will help configuring the devices with these bin ranges which will allow the device to send the unencrypted gift card data.
When a device is shipped with %CompanyName Test/Live keys there is an extra step to add the KSN of the device to our HSM for decryption. This is a common error that is usually easily resolved by contacting %CompanyContact with the EMV and TRACK KSNs from your device.
The first 10 digits of the EMV and TRACK KSNs should be provided.
All issues should be reported to %CompanyContact
When contacting our integrations team please include the following information:
To begin your testing process you should have the following:
The %CompanyName integration team will give you login credentials to the Virtual Terminal and SelfCare reporting system. These credentials should also be used to point your integration to our test host simulator.
You can use SelfCare to view transactions and perform actions such as Refunds/Voids etc.Training on SelfCare/ Virtual Terminal can provided by our support team on request.
To work with our TEST system please note you must have a device with TEST firmware and TEST encryption keys injected in it. Please make sure the firmware is a version that we have validated.
We recommend that you have test cards for each brand you want to use as part of your integration. We also recommend that the cards are capable of the features you wish to support. If needed, test cards can be purchased from ICC Solutions.
(Cards such as Live cards and expired cards should not be used as part of the testing stage of the integration)
The payconfig.xml file is the GoChip configuration file that contains URLs used to access the servers. This file should be added to your project.
The payconfig file contains the following configurations which are described below:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="gatewayLiveUrl">%gatewayLiveUrl</string>
<string name="gatewayTestUrl">%gatewayTestUrl</string>
{gateway=worldnet}{gateway=nuvei}
<string name="gatewayDevUrl">https://devpayments.worldnettps.com/merchant</string>
{/gateway}
<string name="apiKey"></string>
<string name="integrationId"></string>
<string name="logFileAbsoluteDirPath"></string>
<string name="logFileName">log_file.txt</string>
<string name="logFileMaxLines">10000</string>
<string name="logFileMaxFileSize">5MB</string>
<string name="logFileMaxFileCount">0</string>
</resources>
By switching to test mode the SDK will point to gatewayTestUrl when communicating with the server. Test mode should be used for development.
terminal.setMode(CoreMode.TEST);After finishing the development of your app, don't forget to change the mode to Live which will point the SDK to gatewayLiveUrl defined in payconfig file.
terminal.setMode(CoreMode.LIVE);The Dev Mode is used to point to gatewayDevUrl defined in payconfig.xml file. This mode should only be used to test unreleased server features.
terminal.setMode(CoreMode.DEV);When you begin your integration we will provide you a generated test key to add to your payconfig file. You can then add this to the apiKey string which is located underneath the list of hosts.
Once the integration is finished you will be provided with a production key. This will need to replace the test key in the payconfig file.
Log files should be rotated properly based on the settings configured in payconfig.xml file.
default - project directory.
default - log_file.txt
min - 100.
Sample values - 5000 (would be in bytes if no factor), 5KB, 5MB.
max - 20 (to avoid rotating too many files).
| Device | RBA 23.0.2 | RBA 2352 |
| IUC285 | Supported | *Supported |
| IPP320 | Supported | *Supported |
| IPP350 | Supported | *Supported |
*Recommended RBA.
| Device | UPP 7.81.01 | UPP 7.83.35 |
| Lane3000 | *Supported | Not Supported |
| Lane5000 | *Supported | Not Supported |
| Lane7000 | *Supported | Not Supported |
| Self 2000 | *Supported | Not Supported |
| Self 3000 | Not Supported | *Supported |
| Self 4000 | *Supported | Not Supported |
| Self 5000 | *Supported | Not Supported |
*Recommended UPP.
The getDeviceInfo call will return your firmware or RBA version in the logs.
We did a major refactoring on the way our SDK handles the cancellation of transactions. This introduced a new callback and status enum. We also had to remove a couple of errors and messages.
For this release, the changes were only done for Android and Java SDK as well as Websocket.
When you request for the transaction to be canceled by invoking the terminal method
cancelTransaction, you always receive the
CoreMessage TRANSACTION_CANCELLED_BY_USER regardless of the outcome of the cancellation.
The result could either be a successful cancellation request or a failed one in which performing the operation is not permitted.
You get the CoreDeviceError TRANSACTION_CANCELLED when the transaction cancellation is
successfully executed
and CoreError/CoreDeviceError/CoreMessage TRANSACTION_CANNOT_BE_CANCELED_AT_THIS_STAGE when
it's not allowed.
When you cancel the transaction, you either trigger the onCancelTransactionAttempt callback on
the SDK
or receive the message with type RES_ON_CANCEL_TRANSACTION_ATTEMPT on Websocket.
You get the TransactionCancellationStatus from both callback and Websocket message which
describes the cancellation result. Please see the possible values below.
Transaction cancellation coming from the device/device library or done by pressing the cancel button on the payment reader will not trigger the new callback/message.
It's only when the you cancel by calling the terminal method cancelTransaction or sending the Websocket message with type REQ_CANCEL_TRANSACTION.
@Override
public void onCancelTransactionAttempt(TransactionCancellationStatus cancellationStatus) {
AdminLogger.getInstance().log("onCancelTransactionAttempt - " + cancellationStatus, LogLevel.LEVEL_INFO);
switch (cancellationStatus) {
case CANCELLING:
AdminLogger.getInstance().log("CANCELLING - The SDK is currently cancelling the transaction.", LogLevel.LEVEL_INFO);
break;
case NOT_ALLOWED:
AdminLogger.getInstance().log("NOT_ALLOWED - Transaction cannot be cancelled at this stage. e.g. sale is being authorized online", LogLevel.LEVEL_INFO);
break;
case CANCELLED:
AdminLogger.getInstance().log("CANCELLED - The transaction has been cancelled successfully.", LogLevel.LEVEL_INFO);
break;
case NOTHING_TO_CANCEL:
AdminLogger.getInstance().log("NOTHING_TO_CANCEL - There is no transaction to be cancelled.", LogLevel.LEVEL_INFO);
break;
}
}
// CANCELLING
{
"type": "RES_ON_CANCEL_TRANSACTION_ATTEMPT",
"responseType": "RESPONSE_OK",
"data": {
"cancellationStatus": "CANCELLING"
}
}
// NOT_ALLOWED
{
"type": "RES_ON_CANCEL_TRANSACTION_ATTEMPT",
"responseType": "RESPONSE_OK",
"data": {
"cancellationStatus": "NOT_ALLOWED"
}
}
// CANCELLED
{
"type": "RES_ON_CANCEL_TRANSACTION_ATTEMPT",
"responseType": "RESPONSE_OK",
"data": {
"cancellationStatus": "CANCELLED"
}
}
// NOTHING_TO_CANCEL
{
"type": "RES_ON_CANCEL_TRANSACTION_ATTEMPT",
"responseType": "RESPONSE_OK",
"data": {
"cancellationStatus": "NOTHING_TO_CANCEL"
}
}
As stated above, we added new callback and Websocket message and got rid of a couple of errors and messages. Please find below the details on how you should update your code.
We have deleted the TRANSACTION_CANNOT_BE_CANCELED_AT_THIS_STAGE and stopped sending them in the response with types RES_ON_MESSAGE, RES_ON_DEVICE_ERROR
as it's deemed unnecessary.
Additionally, the TRANSACTION_CANCELLED_BY_USER message is now removed and will not be sent in the message with type RES_ON_MESSAGE.
If you are using the TRANSACTION_CANNOT_BE_CANCELED_AT_THIS_STAGE message,
you should now implement the new callback onCancelTransactionAttempt on the SDK and check for the TransactionCancellationStatus.NOT_ALLOWED.
On the Websocket, you should handle the response with type RES_ON_CANCEL_TRANSACTION_ATTEMPT
and check for the cancellationStatus - NOT_ALLOWED
// RES_ON_MESSAGE
{
"type": "RES_ON_MESSAGE",
"responseType": "RESPONSE_OK",
"data": {
"message": "TRANSACTION_CANNOT_BE_CANCELED_AT_THIS_STAGE"
}
}
// RES_ON_DEVICE_ERROR
{
"type": "RES_ON_DEVICE_ERROR",
"responseType": "RESPONSE_ERROR_GENERAL",
"description": "string",
"data": {
"deviceError": "TRANSACTION_CANNOT_BE_CANCELED_AT_THIS_STAGE"
}
}
{
"type": "RES_ON_CANCEL_TRANSACTION_ATTEMPT",
"responseType": "RESPONSE_OK",
"data": {
"cancellationStatus": "NOT_ALLOWED"
}
}
For the TRANSACTION_CANCELLED_BY_USER message,
you should now implement the new callback onCancelTransactionAttempt on the SDK and check for the TransactionCancellationStatus.CANCELLED.
On the Websocket, you now need to handle the response with type RES_ON_CANCEL_TRANSACTION_ATTEMPT
and check for the cancellationStatus - CANCELLED
{
"type": "RES_ON_MESSAGE",
"responseType": "RESPONSE_OK",
"data": {
"message": "TRANSACTION_CANCELLED_BY_USER"
}
}
{
"type": "RES_ON_CANCEL_TRANSACTION_ATTEMPT",
"responseType": "RESPONSE_OK",
"data": {
"cancellationStatus": "CANCELLED"
}
}
We have introduced the new callback onCancelTransactionAttempt in the CoreAPISaleListener interface.
This means you have to add the new method in your class that implements the CoreAPISaleListener.
We added a new dedicated callback that is triggered whenever a network error occurs while a transaction is being authorized online.
This lets you know if you need to perform a reversal.
The new callback onTransactionCommError was added to the CoreAPISaleListener interface
so you are required to implement it in the class that uses the said interface.
When callback is fired, you'll have access to the error as well as the transaction's CoreSale object.
public void OnTransactionCommError(CoreSale sale, CoreError error, string message)
{
}
@Override
public void onTransactionCommError(CoreSale sale, CoreError error, String message) {
}
- (void)onTransactionCommError:(CoreSale*)sale withError:(CoreError) error withMessage:(NSString*)message{
}
{
"type": "RES_ON_TRANSACTION_COMM_ERROR",
"responseType": "RESPONSE_ERROR_GENERAL",
"data": {
"sale": {
// sale object
},
"error": "ERROR_TIMEOUT",
"message": "timeout"
},
"description": "onTransactionCommError"
}
| Device | FW v1.14.0 |
| DX4000 | *Supported |
| DX8000 | *Supported |
| RX7000 | *Supported |
*Recommended Axium FW.