Android - Version 1.4.4

What's new!

  • Added support for sending signature after the transaction is processed (as a field in CoreUpdate)
  • Added support to register a Secure Card via payment request without MerchantRef
  • Various Bug fixes and improvements
  • Fixed various Sample App issues
  • Fixed various Sample App issues
  • Added support for sending signature after the transaction is processed (as a field in CoreUpdate)
  • Added support for sending device serial number to the server for all BBPos devices
  • Added support to register a Secure Card via payment request without MerchantRef
  • Transaction can now be started in a quick-chip mode for BBPos devices
  • Various Bug fixes and improvements
  • Fixed various Sample App issues
  • Fixed various Sample App issues
  • Added support for sending signature after the transaction is processed (as a field in CoreUpdate)
  • Added support for sending device serial number to the server for all BBPos devices
  • Added support to register a Secure Card via payment request without MerchantRef
  • Transaction can now be started in a quick-chip mode for BBPos devices
  • Various Bug fixes and improvements
  • Fixed various Sample App issues
  • Fixed various Sample App issues
  • Added support for sending signature after the transaction is processed (as a field in CoreUpdate)
  • Added support for sending device serial number to the server for all BBPos devices
  • Added support to register a Secure Card via payment request without MerchantRef
  • Transaction can now be started in a quick-chip mode for BBPos devices
  • Various Bug fixes and improvements
  • Fixed various Sample App issues
  • Fixed various Sample App issues
  • Various Bug fixes and improvements

Introduction to The SDK

The CoChip SDK is an “easy to use” library to handle communication with the PayConex Plus payment gateway. The SDK wraps a set of interfaces to communicate with the PayConex Plus payment gateway, with the card device reader libs and the client's side security, making it even easier to connect.

If you are interested on more details, visit the Understanding the SDK section, and get a better sense of the communication flows between the components and how they interact.

Now, follow the next sections, and their steps, to implement your solution.

If you have questions, please talk to us using the Contact link at the top (right side) of this page. We would love to help!

Download The Components

Step 01 - Download the SDK

The SDK has 2 main components: CoChip SDK and Plugins (Optional). If you are using one (or more) of the following devices you can add the corresponding plugin.


If you are using a card reader device, don't forget to select one (or more) of the plugins above before hitting the download button. This way, you are going to download the plugins' packages and the SDK.

Step 02 - Download the Sample App

The Sample app, as the name states, represents an example of how to use the CoChip SDK in your own app.

We recommend, in case you are developing your application from scratch, that you give it a try to the Sample App, and perform a few tests before implementing your own code. By doing so, you can be more comfortable in implement your own logic, or in copying structures to easy your development work.

Download Sample App

Basic Settings and Initialisation

Requirements

  • This platform and version targets the Android version 4.4.

Step 01 - SDK Installation

The installation of the SDK is as easy as adding the CoChip SDK to your project. For that you need:

I) Copy the core-sdk.jar to the application folder and add it as a dependency.

II) Go to the AndroidManifest.xml and set these permissions.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

III) Copy payconfig.xml into your project's res/values directory.

The payconfig.xml file contains URLs used to access the servers, so don't forget to add it to your project, or the communication is not going to happpen.

If you want to start with the sample app, just follow the steps of creating a new project from an existing source. Each IDE works in a different way, but most of them offers you, when creating a new project, to create it based on a existing project or based on source files, where you just have to point to a repository - this repository would be the decompressed folder of the Sample App, in the last step of the previous section.

Step 02 - Implementing the CoreAPIListener

The application needs to implement the Core API Listener (CoreAPIListener) to interact with the SDK.

On Android this makes the most sense in the MainActivity, as follows:

  • public class MainActivity implements CoreAPIListener{


If you want more details on CoreAPIListener, consult the Core API Listener page at the SDK Documentation section.

Step 03 - Terminal Initialisation

I) An instance of a Terminal must be created first.

Where this is an object that implements the CoreAPIListener (i.e. this code snippet is done inside the MainActivity)

  • AndroidTerminal terminal = new AndroidTerminal(this);


II) Now, set the Terminal Mode, (TEST, DEV or LIVE), depending on your needs.

This is an easy one as well. All you have to do is to set the terminal mode to the right type.

The Test Mode should be used for development - It's going to make your app to use the gatewayTestUrl defined in payconfig.xml when communicating with the server. Before initiate your Terminal, enable the Test Mode:

  • terminal.setMode(CoreMode.TEST);


After finishing the development of your app, don't forget to change the mode again to go Live (Live Mode, that points to gatewayLiveUrl defined in payconfig.xml file).

  • terminal.setMode(CoreMode.LIVE);


You still have one option: the Dev Mode.

  • terminal.setMode(CoreMode.DEV);


The Dev Mode is used to point to gatewayDevUrl defined in payconfig.xml file. The Dev Host usually contains unreleased features.

III) Once the Terminal is created, initialise it.

The arguments are the terminal ID and secret. These are credentials required to use a Terminal using the SDK.

  • terminal.initWithConfiguration(MainActivity.this, TERMINAL_ID, SECRET);


Step 04 - Handling the Initialisation Response

Once the Terminal is initialised, you need to treat the possible responses.

The Terminal initialisation tries to connect to the server, and the response needs to be verified. The SDK does that with the methods: onError and onSettingsRetrieved.

Successful Response

If your initialisation worked properly, without problems, your application is going to receive the response at the onSettingsRetrieved method.

  • @Override
    public void onSettingsRetrieved(CoreSettings settings) {
    	// ...
    }


You need to use the argument returned to extract the response.

Unsuccessful Response

If anything went wrong with the initialisation, your applicaton is going to receive an error at the onError method.

  • @Override
    public void onError(CoreError error, String message) {
    	Log.d(TAG, "onError");
    	// ... treatment for initialisation error
    }


In this case, your application can show the error, a generic message, or even, execute a particular treatment for the error, depending on the cause.

Step 05 - Plugin Installation

I) Copy the appropriate plugin(s) to your project folder.

II) Add the plugin libraries as dependencies for the project.

III) Additional Frameworks Required per Device, in case you are using any of the plugins.

  • BBPosDevice
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  • Rambler
<uses-permission android:name="android.permission.RECORD_AUDIO"/> 
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>

Step 06 - Initialise the Device

Now we can initialise the device using our Terminal.

The first argument is a DeviceEnum corresponding to the device your application is going to use. The second argument is a connection type. The third argument is optional for iniatilising a bluetooth device with a pre stored bluetooth address.

  • terminal.initDevice(DeviceEnum.BBPosDevice, DeviceConnectionType.BLUETOOTH, null);


For devices connecting via bluetooth, onSelectBTDevice method will return list of available devices. We need to choose the device from the list to be able to connect to it.

  • @Override
    public void onSelectBTDevice(ArrayList<String> type) {
    	// ...
    }


Make sure to call selectBTDevice (to connect to the device) passing the position of the device from the list. The argument passed is the position of the device selected by the user from the list returned by the onSelectBTDevice method before.

  • terminal.selectBTDevice(0);


Implementing Transactions

Step 01 - Create the CoreSale object

Create a CoreSale object with the amount.

For transactions using a card device reader (plugins)


For keyed transactions:

  • CoreSaleKeyed saleKeyed = new CoreSaleKeyed(BigDecimal.valueOf(12.3));
    saleKeyed.setCardHolderName("Test user");
    saleKeyed.setCardNumber("4111111111111111");
    saleKeyed.setCardCvv("123");
    saleKeyed.setCardType("VISA");
    saleKeyed.setExpiryDate("1218");
    terminal.processSale(saleKeyed);


Make sure onSettingsRetrieved method has been called before processing any transaction.

Step 02 - Send the transaction online

Call the method processSale from the Terminal object, passing the sale object as the parameter.

  • terminal.processSale(sale);


Step 03 - Handle the response

Succesful Response

If all goes well, a response is returned at the method onSaleResponse.

The response argument needs to be treated so your solution identify its status. Depending on the status, which coul be one of the following, your transaction might be approved or declined.

  • A - Approval: Transaction was approved.
  • D - Declined: Transaction was declined.
  • C - Pick Up: Transaction was declined. Type of decline which means that the card has been marked as lost or stolen by the cardholder.
  • R - Referral: Transaction was declined. Type of decline which means that the card has been marked as lost or stolen by the cardholder.

For the transaction to be approved, the response code must be A. Your Solution NEEDS TO VERIFY THE RESPONSE STATUS before continuing, once the successful response itself doesn't guarantee that the transaction was accepted.

  • @Override
    public void onSaleResponse(final CoreSaleResponse response) {
       String json = response.getAsJsonObject();
       Log.d(TAG, "onSaleResponse ");
    }


Unsuccessful Response (Error)

If, for any reason, the request doens't go well, the onError method is fired with an error message.

  • @Override
    public void onError(CoreError coreError, String s) {
       Log.d(TAG, "onError");
       // ... treatment for initialisation error
       // ... treatment for transaction execution error
    }


Using the Signature

There are 2 types of transactions that require a signature to be sent with the request.

  • All swiped transactions
  • Chip and signature transactions

If the signature is collected on the paper receipt please set SignatureCollection field of the CoreSale object to “MANUAL”. This property will make sure that onSignatureRequired is not triggered.

To send a signature you need to collect the details and send them via the CoreSignature object.

Step 01 - Get an Instance of CoreSignature.

The CoreSignature object is created and supplied to your application via onSignatureRequired method:

  • @Override
    public void onSignatureRequired(final CoreSignature signature) {
       Log.d(TAG, "onSignatureRequired");
       signatureCanvas.setSignature(signature); // View object with signature member variable
    }


You can use the following methods to manipulate the signature object.

  • StartTouch - User has reapplied their finger.
  • MoveTouch - User has moved their finger.
  • UpTouch - The user has lifted their finger.
  • ClearSignature - Clears the signature.
  • SubmitSignature - Submits the signature.

For more details and descriptions on those methods, access the CoreSignature class documentation at the SDK Documentation section.

Step 02 - Populate the CoreSignature object

Use a canvas to call the corresponding signature touch method on the user input.

  • @Override
    public boolean onTouchEvent(MotionEvent event) {
       float x = event.getX();
       float y = event.getY();
     
       switch (event.getAction()) {
          case MotionEvent.ACTION_DOWN:
             signature.startTouch(x, y);
             break;
          case MotionEvent.ACTION_MOVE:
             signature.moveTouch(x, y);
             break;
          case MotionEvent.ACTION_UP:
             signature.upTouch();
             break;
      }
     
      return true;
    }


Step 03 - Send the CoreSignature object

When the signature is completed, submitSignature method should be called to let the SDK know that the user has completed the signature.

  • terminal.submitSignature(signature);