On-Demand Functions

Besides processing transactions, CSDK offers various on-demand features to realize different functions. The supported features are listed below:

• Account Validation
• Get Account Information
• Set Credential
• Update PIN
• Upload Log
• Query Tids

Account Validation

We can use this function to verify if the combination of merchant ID and client ID passed to CSDK is valid.

We'll first create an instance of com.elavon.commerce.ECLAccountValidationListener, as shown below.

// The following code is copied from MainActivity.java in the sample application code.
// The code only displayed results on UI.
 
ECLAccountValidationListener delegate = new ECLAccountValidationListener()
{
    @Override
    public void accountDidValidate(ECLAccountInterface eclAccountInterface)
    {
        displayMessageInProgressView("Account Validated", false);
    }
 
    @Override
    public void accountDidFailToValidate(ECLAccountInterface eclAccountInterface, ECCError eccError)
    {
        displayErrorInProgressView("Account Validation Failed", eccError);
    }
};

We'll then pass the instance to method validateAccount on interface com.elavon.commerce.ECLAccountInterface.  CSDK internally validates that the combination of merchant id and client id provided by POS System (through com.elavon.commerce.ECLOpayoAccountListener) is correct. If error occurs at any stage during the validation, ECLCommerceError.Codes.ECLAccountInvalidCredentials will be returned in ECLAccountValidationListener.accountDidFailToValidate.

TransactionSavedState.INSTANCE.account.validateAccount(delegate);

Get Account Information

We can use this function to do a full TMS update on card reader under current merchant ID and client ID.

We'll first create an instance of com.elavon.commerce.ECLAccountInformationRetrievalListener, as shown below:

// The following code is copied from MainActivity.java in the sample application code.
// The code only displayed results on UI.
 
ECLAccountInformationRetrievalListener delegate = new ECLAccountInformationRetrievalListener()
{
    @Override
    public void accountInformationRetrievalDidSucceed(ECLAccountInterface account, ECLAccountInformation accountInformation)
    {
        MainActivity.this.accountInfo = accountInformation;
        displayAccountSettings(account, accountInformation);
    }
 
    @Override
    public void accountInformationRetrievalDidFail(ECLAccountInterface account, ECCError eccError)
    {
        displayErrorInProgressView("Account Info Retrieval Failed", eccError);
    }
};

We'll then pass the instance to method retrieveAccountInformation on interface com.elavon.commerce.ECLAccountInterface.

TransactionSavedState.INSTANCE.account.retrieveAccountInformation(delegate);

Set Credential

We can use this function to cache a set of mechant ID and client ID in memory for CSDK.

We'll first create an instance of com.elavon.commerce.ECLAccountCredential.

// The following code is copied from MainActivity.java in the sample application code
// Here we only need to set two attributes
 
class Defines
{
    public static final String MERCHANT_ID = "merchantID";
    public static final String CLIENT_ID = "clientID";
    public static final String PIN= "pin";
}
 
HashMap<String, ECCSensitiveData> accountCredentialAttributes =
new HashMap<String, ECCSensitiveData>()
{
    {
        put(Defines.MERCHANT_ID, new ECCSensitiveData(merchantIDEditText.getText().toString()));    // mandatory
        put(Defines.CLIENT_ID, new ECCSensitiveData(userIDEditText.getText().toString()));          // mandatory
        put(Defines.PIN, new ECCSensitiveData(PINEditText.getText().toString()));                   // optional
    }
};
 
ECLAccountCredential accountCredential = new ECLAccountCredential(accountCredentialAttributes);

Then we'll create an instance of com.elavon.commerce.ECLSetCredentialListener.

// The following code is copied from MainActivity.java in the sample application code
// Besides displaying result in UI, this code block does an extra step of account validation.
 
ECLSetCredentialListener setCredentialListener = new ECLSetCredentialListener()
{
    @Override
    public void credentialDidSet(ECLAccountInterface eclAccountInterface)
    {
        activity.displayMessageInProgressView("successfully saved account settings", false);
        activity.displayMessageInProgressView("Validating new account settings...", false);
         
        // It does a round of credential valiadation.
        if (account != null) {
            account.propertiesDidChange(new ECLAccountValidationListener() {
                @Override
                public void accountDidValidate(ECLAccountInterface eclAccountInterface) {
                    activity.displayMessageInProgressView("Account validation successful", false);
                }
 
                @Override
                public void accountDidFailToValidate(ECLAccountInterface eclAccountInterface, ECCError eccError) {
                    activity.displayMessageInProgressView("Account validation problem: " + eccError, false);
                }
            });
        }
    }
 
    @Override
    public void credentialDidFailToSet(ECLAccountInterface eclAccountInterface, ECCError eccError)
    {
        activity.displayMessageInProgressView("failed to save account settings: " + eccError, false);
    }
}

We'll then pass the instances to method setCredential on interface com.elavon.commerce.ECLAccountInterface.  CSDK internally caches merchant ID and client ID in memory. If there is error, ECLCommerceError.Codes.ECLSetCredentialFail will be returned in ECLSetCredentialListener.credentialDidFailToSet.

account.setCredential(new ECLAccountCredential(accountCredential, setCredentialListener);

Update PIN

We can use this function to set or update the operator PIN for the current combination of merchant ID and client ID. The default value for the operator PIN is empty. If set to a different value, it must be returned in method getPin of com.elavon.commerce.ECLOpayoAccountListener and must be set in the instantiation of com.elavon.commerce.ECLAccountCredential.

We'll first create an instance of com.elavon.commerce.ECCSensitiveData with pin data.

// newPin is String type, holding the new or updated pin data.
ECCSentiveData pinData = new ECCSensitiveData(newPin);

Then we'll create an instance of com.elavon.commerce.ECLGeneralOperationListener.

// The following code is copied from MainActivity.java in the sample application code.
// The implementation simply displays any progress on UI except that the pin value is persisted into device storage
// when the operation is successfully completed.
 
ECLGeneralOperationListener generalOperationListener = new ECLGeneralOperationListener()
{
    // progress should be ECLTransactionProgress.PIN_UPDATE_STARTING.
    @Override
    public void started(ECLTransactionProgress progress)
    {
        displayMessageInProgressView("Pin update started", false);
    }
 
    // There shhould be no progress update for this operation.
    @Override
    public void progress(ECLTransactionProgress progress)
    {
        displayMessageInProgressView("Pin update progress:  " + progress, false);
    }
 
    // progress should be ECLTransactionProgress.PIN_UPDATE_COMPLETED.
    @Override
    public void completed(boolean success, ECLTransactionProgress progress, ECCError eccError)
    {
        if (success)
        {
            displayMessageInProgressView("Pin update successfully completed", false);
            final SharedPreferences.Editor editor = credentials.edit();
            editor.putString(Defines.PIN, newPin);
            editor.commit();
            displayMessageInProgressView("New Pin is persisted", false);
        }
        else
        {
            displayMessageInProgressView("Pin update completed but failed", false);
        }
    }
};

We'll then pass the instances to method updatePin on interface com.elavon.commerce.ECLOpayoAccountInterface and CSDK internally will send the pin data to Opayo server. The possible errors are:

• ECLCommerceError.Codes.ECLPinUpdateNotSupported if pin update is not allowed
• ECLCommerceError.Codes.ECLPinUpdateFailure for any other error during the operation. 

ECLOpayoAccountInterface opayoAccount = (ECLOpayoAccountInterface)TransactionSavedState.INSTANCE.account;
opayoAccount.updatePin(pinData, generalOperationListener);

Upload Log

We can use this function to upload log to Opayo server. This is very helpful when troubleshooting merchant's issues.

We'll first create an instance of com.elavon.commerce.ECLGeneralOperationListener.

// The following code is copied from MainActivity.java in the sample application code.
 
ECLGeneralOperationListener logUploadListener = new ECLGeneralOperationListener()
{
    // Progress here for this operation is ECLTransactionProgress.LOG_UPLOAD_STARTING
    @Override
    public void started(ECLTransactionProgress progress)
    {
        displayMessageInProgressView("Upload Log: started", false);
    }
 
    // There is no progress update here.
    @Override
    public void progress(ECLTransactionProgress eclTransactionProgress)
    {
        displayMessageInProgressView("Upload Log: progress " + eclTransactionProgress, false);
    }
 
    // Progress here for this operation is ECLTransactionProgress.LOG_UPLOAD_COMPLETED
    @Override
    public void completed(boolean success, ECLTransactionProgress progress, ECCError eccError)
    {
        if (success)
        {
            displayMessageInProgressView("Upload Log: completed", false);
        }
        else
        {
            displayMessageInProgressView("Upload Log: failed " + eccError.getDescription(""), false);
        }
    }
};

Then we'll pass the instance to method uploadLog on interface com.elavon.commerce.ECLOpayoAccountInterface. CDSK will internally upload internal operation log to Opayo server. This operation can take up to 1 minute to complete. The possible errors are:

• ECLCommerceError.Codes.ECLCardReaderConfigurationUpdateFailed when TMS update is required
• ECLCommerceError.Codes.ECLUnableToInitialize when CSDK is not properly initialized

ECLOpayoAccountInterface opayoAccount = (ECLOpayoAccountInterface)TransactionSavedState.INSTANCE.account;
opayoAccount.uploadLog(logUploadListener);

Query Tids

We can use this function to query available client IDs for particular merchant ID.

We'll first create an instance of com.elavon.commerce.ECLTidQueryListener.

// The following code is copied from MainActivity.java in the sample application code
// This sample only displays results in UI.
 
ECLTidQueryListener tidQueryListener = new ECLTidQueryListener()
{
    @Override
    public void started()
    {
        displayMessageInProgressView("query tids (MID: " + input.getText().toString() + ") started", false);
    }
 
    @Override
    public void completed(boolean success, String s, List<String> list, ECCError eccError)
    {
        if (success)
        {
            displayMessageInProgressView("query tids (MID: " + input.getText().toString() + ") succeeded", false);
            if (list != null && list.size() != 0)
            {
                for (String tid : list)
                {
                    displayMessageInProgressView("TID: " + tid, false);
                }
            }
            else
            {
                displayMessageInProgressView("query tids (MID: " + input.getText().toString() + ") no tid", false);
            }
        }
        else
        {
            displayMessageInProgressView("query tids (MID: " + input.getText().toString() + ") failed " + eccError.getDescription(""), false);
        }
    }
};

We'll then pass the instance to method queryTIDs on interface com.elavon.commerce.ECLOpayoAccountInterface. CSDK internally will send request to Opayo Server to get the list the available client IDs for a given merchant ID.

ECLOpayoAccountInterface opayoAccount = (ECLOpayoAccountInterface)TransactionSavedState.INSTANCE.account;
opayoAccount.queryTIDs(mid, tidQueryListener);