Utilities|Resources‎ > ‎STBridge‎ > ‎

STBridge Tutorial

HCE Virtual Card Life Cycle Management With STBridge.

The following document offers an overview of Card life Cycle Management with STBridge. After reviewing this document you should be able to preform the following user actions.

Accessing Card in cloud

  •       Preparing STBridge.jar file to be executable
  •       Create test cards
  •       Connecting to card in cloud via STBridge.
  •       Running perso scripts form command line
  •       Understanding parameters used to run STBridge

Card management 

  •      Executing card deactivation script
  •      Executing card activation script
  •      Executing card deletion script

SimplyTapp offers STBridge as tool to manage card life cycle. STBridge allows an issuer to connect to a virtual card instance in the SimplyTapp cloud. 

STBridge is used to communicate APDUs, and other GP commands, to a specific virtual card residing in the cloud platform.

STBridge does support standard GPJ shell commands.

STBridge download available in our IssuerSDK bundle. 

STBridge uses gpjNG as the shell client unless -noshell is passed.

Creating a Virtual Card in the Cloud 

A prerequisite to running STBridge is you must have created a virtual card residing in the cloud to connect to.

To learn how to create a virtual card please refer to SimplyTapp’s Self Driven HCE Pilot.

STBridge packaged as an executable jar (STBridge) and can be executed like this:

java -jar STBridge.jar -ck consumer_key -cs consumer_secret -at access_token_to_card -ts access_token_secret [-s jcsh_script_to_run

STBridge Paramater list:

-ck the issuer consumer key

-cs the issuer consumer secret

-at the card access token

-ts the card access token secret

Download STBridge

There are various ways for obtaining the parameters from a virtual card in cloud needed to execute STBridge.

Cards created with SimplyBank.us

If you are using a card you created thru SimplyBank.us according to our Full Circle Demo you will need to prepare STBridge.jar to connect with your specific card in the cloud.

 You can find your
  -ck consumer_key -cs consumer_secret -at access_token_to_cardIn the issuer tab of the portal. They are also called Issuer Key and Issuer Secret.


You can find your  -at access_token_to_card -ts access_token_secret at the bottom of the  page  SimplyBank.us apply page after the perso script is run. They are referred to as Oauth access token and Secret. After you run your perso script on the SimplyBank.us page it will generate the access token and access token secrets.

Test Card Created Using Web Portal Interface.

If you have an issuer account and card brand within the SimplyTapp Developers portal test cards can be generated. From within the card brand you can create a test card by clicking create test card.

The executable STBridge.jar file is created and labeled Utility Connection. Example below of generated test card.


When using a card created from the web portal interface you must run perso script before you can run card management scripts.

Append the perso script you have stored locally to your STBridge.jar script with containing all necessary parameters and execute.


java -jar STBridge.jar -ck 0zAfDc7mGIIKlXJTGZSBrdMDHdq7eVGLo5wmG9gA -cs 5KZgaLHCagyK3KvZzXtDtCJq9cG1ukSDKvsdbhK1 -at d2KtVkWaNIf7a1pzAz0JMMR7XMQ4wgzy2ezMPZzI -ts n0U6Fa2dNllXUE0aNIMmdxXYr7iTZEw0lZT4EKGV -s Desktop/vcbp_perso_card.jcsh

Once you have run perso script for your test card you can alter state of card.

*If you are working with a card generated with SimplyBank.us  then perso script has already been run. Running a perso script from command line is not needed.

Managing An Active Card

Appending scripts to the STBridge.jar executable file allows one to manage card life cycle. The following are examples of how to manage card life cycle.

After perso, the card is in activated state.

After perso, you can run any various scripts. Activating an activated card does nothing and deactivating a deactivated card does nothing, but scripts will run.

When changing the state of the card a GCM message will trigger in the cloud and be sent to the appropriate card agent in the mobile device. GCM is generated only if there is a state change. Enabling an already enabled card or disabling an already disabled card does not trigger GCM message. Messages will also be displayed in app when using our Tapp App. Available for download http://wiki.simplytapp.com/software-dev-kits/mobile-sdk. 

Deactivate Card.

vcbp_deactivate_card.jcsh is script to deactivate the card. 

After running the script, the card agent is disabled from performing contact-less transactions.

Activate card

vcbp_activate_card.jcsh is script to activate the card again. 

After running the script, the card agent is enabled to perform contact-less transactions.

Terminate card

vcbp_terminate_card.jcsh is script to terminate the card.

 After running the script, the card agent is disabled from performing contact-less transaction. The card agent does not load anymore after refreshing/restarting the wallet. This is like a kill switch, the state cannot be changed from terminated.

Running vcbp_terminate_card script updates the card state in the database to "dead". That causes the card to be removed from "Your Card Apps" and from the mobile apps in Developers portal UI . 

Once a card is terminated it is marked as dead and can not be recovered to active state from  the data base.