Developing for Android

The Android platform uses the MintChip Java API found within the API Reference section of this web-site. To help you quickly get coding on Android with the MintChip Java API we provide a sample package.

The latest Android sample package can be found within the download section of this site.

The MintChip Sample application demonstrates the following concepts:

  • Building and deploying an Android application that uses the MintChip API
  • Using the MintChip API to:
    • Create a Value Message (.ecn file)
    • Accept a Value Message (.ecn file)
    • Read the MintChip transaction log
    • Read the MintChip information and status

The MintChip Sample application presented here has been developed with the intention to make the understanding of these concepts as straightforward as possible. Even though it is a fully functional application, in order to achieve these goals some of the common development practices have been foregone. The application cannot be considered production ready and is not intended for any other usage but to be a sample demonstration of the MintChip Java API specifications.

Prerequisites

To deploy and run the pre-built application the following are required:

  • An Android phone running the Android OS version 2.3.3 or higher.
  • A MintChip microSD card installed within the phone.

To create a development project in order to compile the code it is recommended to use the Android Development Tools (ADT) Plug-in for the Eclipse IDE that can be downloaded from the Android developers site.

What's in the Sample Package

The MintChip Sample application package includes two folder:

  • project, which contains the Android Java Eclipse project with the application source code.
  • setup, which contains the MintChipSample.apk, an Android application package file (APK) that can be used to deploy the sample application to an Android phone. This folder also contains JAR files and Android native libraries (.so files) that can be used to build Android applications that use the MintChip Java API.

How to use the MintChip Java API

The MintChip API are implemented by the classes contained in the ca.mint.mintchip.android.api and ca.mint.mintchip.contract packages.

A typical approach to using the MintChip API in an Android application would involve the following steps.

  1. Reference the ca.mint.mintchip.android.api and ca.mint.mintchip.contract Java packages. This can be done by referencing the following JAR files from the Android Eclipse project:
    • MintChipAndroidAPi.jar
    • MintChipCommon.jar
  2. Add the following Android native libraries to your Eclipse project under the libs/armeabi folder:
    • libMintChip.so
    • libSDSCi.so
  3. In the AndroidManifest.xml file request the WRITE_EXTERNAL_STORAGE permission so that the application can access the MintChip on the microSD card:
    <uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />        
    
  4. Import the MintChip API packages into your source code file:
    import ca.mint.mintchip.android.api.*;
    import ca.mint.mintchip.contract.*;
    
  5. Create an instance of the class that implements the IMintChip interface, which is the main interface to invoke the MintChip functionality:
    IMintChip mintChip = MintChipFactory.getInstance().createMintChip();
    
  6. Use MessageFactory to instantiate message types:
    IValueRequestMessage request = (IValueRequestMessage)
        MessageFactory.getInstance().toMessage(base64Request);
    
  7. Call methods of the IMintChip interface and be prepared to handle the MintChip Exception:
    IValueMessage valueMessage;
    try {
        valueMessage = mintChip.createValueMessage(request);
    } catch (MintChipException e) {
        //TODO Handle the exception
    }
    

Please see the MintChipUtility.java source code file included in the MintChipSample project for more examples on how the MintChip API can be used to create value messages, accept payments in the form of value of value message, read the transaction log and the detailed information of the MintChip installed on a Android device.