Navigation

Creating your first Java Card applet

What is a Java Card applet?

A Java Card applet is nothing more than a small program written for running in a payments environment like a chip card or a smartcard.

Working with Java Card applets

Because Java Card is it own programming language it is important that you have a development environment to work on in. The first thing you need to do is install the SimplyTapp Issuer SDK.

Installing the Issuer SDK

Step 1 - Download Issuer SDK- The Issuer SDK includes many applet examples as well as a simulator to test them.

Step 2 - Modify applets (if desired) and test - We provide gradle commands to make building and testing the applets easy.

SDK Layout==========

IssuerSdkBundle directories:

- bin: Mac/Linux/Windows scripts for "cardsim" and "gpj".

- CardApplet: Library project for your JavaCard applets. For running and debugging, see the dependent library list used in CardApplets/build.gradle. Your main should be set to com.simplytapp.cardwrapper.CardWrapper.

Applet programming note: All classes needing persistent state through the applet lifecycle must implement java.io.Serializable. Our simulator's javacard.framework.Applet class already does this for you. Setting serialVersionUID is not required, as state is never persisted beyond the lifetime of an installed applet.

- CardAgent: Library project for your applet agents

- CardAgentTesterApp: Android application to test your applet agents. By default it tests the the agent from the CardAgent project/directory. If you wish to test CardAgent-PayPass or CardAgent-VisaMSD-SwipeYours, change the dependent project in CardAgentTesterApp/build.gradle.

- CardApplet-PayPass - CardAgent-PayPass

An extra example set of applets with an agent to perform Mastercard's PayPass protocol.

- CardAgent-VisaMSD-SwipeYours - CardApplet-VisaMSD-SwipeYours

An extra example set of applets with an agent to perform Visa's MSD (Magnetic Stripe Data) protocol using magnetic stripe data from a physical card (see the Full Circle demo on http://wiki.simplytapp.com for additional information).

Android Studio Setup
====================
* Select "Import Project"
* Select the build.gradle file in the topmost SDK directory
* Use default gradle wrapper (if you have gradle 1.8 installed, using the local
installation will also work).
Gradle and command line builds
==============================
We've included gradle files (tested with version 1.8) to help you get the SDK up in
running in your IDE more quickly. Gradle wrapper, "gradlew", is provided to
bootstrap Gradle version 1.8. If you already have 1.8 installed, you can just use
the gradle command directly.
The CardAgentTesterApp might not be able to determine the location of your Android
SDK directory to build. (The error message will be clear when this is the case.)
If this happens, set an environment variable ANDROID_HOME to you android SDK
directory.
To do a clean build of all projects, use:
./gradlew clean build
The build results are in "build/" subdirectories:
CardApplet/build/libs/CardApplet.jar CardAgent/build/libs/CardAgent.jar

CardAgentTesterApp/build/apk/CardAgentTesterApp-*.apk
If you want to build just a single sub-project, execute gradlew from the
project's subdirectory (1), or prefix the build target with :Subproject: (2).
Example:
Method 1:
[~/IssuerSdkBundle/CardApplet]$ ../gradlew build
Method 2:
[~/IssuerSdkBundle]$ ./gradlew :CardApplet:build
Beside the "build" target, there is also a "clean" target and a "run" targetwhich will run the applet against the test.jcsh file in the applet's directory.

Eclipse (Android Developer Tools Version)
=========================================
We've configured gradle to generate eclipse project files. To generate eclipse
project files use:
./gradlew eclipse
After that you can do File => Import => Existing Project into workspace. The root
Directory is this README's directory. Uncheck "copy projects into workspace" in
the event that the box is checked.

If using an IDE, you will need to set your main class to "com.simplytapp.cardwrapper.CardWrapper"

The CardApplet.jar file is now a Java Card applet package that can be uploaded to the SimplyTapp cloud.

Java Card Development

Chances are that you will want to modify or create your own Java Card applet. Here's an explanation of some of the files included in the SDK.

The project files in the package name "com.st" include:

CardApplet.java - Implemented payment protocol applet

Ppse2Pay.java - PPSE selection applet

Both of these applets include the "process" method which receives message APDU's from the POS device.

As a card credential issuer, it is important to understand how to manage the lifecycle of a card credential. The default shell with the tools provided is gpjNG..oh yeah, we went original with the "Next Generation"! gpj is a simple command line tool used to install, personalize, transact, and delete card applets in the card credential environment.

Let's look at the test.jcsh included in the SDK as an example of using gpjNG to install card applets. When debugging the project in an IDE or on the command line, your simulator should by default initialize with gpjNG as the shell and response with a header that looks like this:

The gpjNG script to personalize the example card applets looks like this:

# Using the simulator is simple. Configure your IDE to use
# com.simplytapp.cardwrapper.CardWrapper as your main class and you
# can set debugger breakpoints inside your applet for interactive testing.
#
# The most common commands that you will issue against the applet are
# included in this test script:
# Reset the card (same as /atr) and then selects default card manager:
/card
# Open a secure channel to card manager
auth
# install -i <instance-AID> C9#([install-params]) <package-AID> <applet-AID>
#
# Install the PPSE (Proximity Payment Secure Environment) and the specified
# card applet to the simulator.
#
# We allow use of a pipe symbol in these commands which converts ascii
# symbols into hex. For example:
#
# |com.st is shorthand for: 636f6d2e7374
# |Ppse2Pay is shorthand for: 5070736532506179
# |CardApplet is shorthand for: 436172644170706c6574
#
# Our JavaCard implementation does not have a 16 character AID size limit that
# standard JavaCard implementations have.
#
# The first command installs the PPSE applet using its standard name
# in widespread use on payment terminals: "2PAY.SYS.DDF01"
# (325041592e5359532e4444463031). The C9# pararmeter personalizes the default
# card applet ID of the point of sale applet. A0000000031010 is the
# registered VISA AID.
install -i |2PAY.SYS.DDF01 -q C9#(A0000000031010) |com.st |Ppse2Pay
#
# The second command installs our test applet as VISA's AID (A0000000031010).
# This is just a stub applet that doesn't respond to any instructions.
#
install -i A0000000031010 -q C9#() |com.st |CardApplet
# Example commands to select individual applets for testing:
/select |2PAY.SYS.DDF01
/select A0000000031010
/atr
#
# special commands:
# exit - this exits the shell and simulator
# exit-shell - this only exits the shell but leaves the simulator running
#
# "exit-shell" may be used to disconnect from the shell (after card setup)
# and then re-connect from the card-agent development project
#
#exit