MintChip API

As previously described in this guide, the MintChip can be used on many computing platforms. On all platforms MintChip provides the following functionality:

  • Processing credit transactions by loading the Value Messages and incrementing the chip's balance.
  • Processing debit transactions by creating the Value Messages and decrementing the chip's balance.
  • Reading the transaction log and returning a collection of debit or credit transaction records.
  • Providing the chip's status, consisting of data that may change over the chip's lifetime (i.e. the balance, the maximum allowed debit and credit amounts, current and remaining numbers of the transaction records).
  • Providing the chip's properties, consisting of data that never changes since chip's initialisation (i.e. the ID, the currency code, the public certificate and the chip version).

Local (Physical) MintChip

Currently, the physical MintChip can be used with Android and BlackBerry smart-phones and Windows based PCs. In order to support development of native applications and Web based applications for these platforms, the Royal Canadian Mint developed a set of MintChip APIs for Java, .NET and JavaScript. These APIs share the same object model and the same semantics to support the MintChip functionality. The differences between these platform specific APIs are mostly syntactic. Detailed descriptions of the MintChip API for each platform can be found in the API Reference on this site. The Downloads page provides sample applications implemented for each of the supported platforms using the platform specific MintChip API.

Remote (Hosted) MintChip

Hosted MintChip Services are an alternative way to access MintChip functionality from devices which do not support microSD cards, for example the iPhone.

In this scenario the MintChip is held remotely (hosted). A number of MintChips are installed on a special hardware security module (HSM) and connected to a Remote MintChip server. The Remote MintChip server provides three types of functionality:

  • A Remote MintChip Account home page. This can be accessed by pointing a browser to https://remote.mintchipchallenge.com.
  • A Hosted MintChip HTTP API. These Web services are intended to be consumed by custom client applications and plugins that are developed for the iPhone or other devices. The API specification is detailed in the Hosted API Reference on this site.
  • An HTML-based payment authorization URL for integration with merchant websites. This can be used by Web merchants to request payments against a hosted consumer MintChip, and where the transaction is purely browser-based. It is intended specifically for cases where the client device does not have any MintChip application or plugin to act as an intermediary to the HTTP API. The process is detailed in the Hosted API Reference on this site.

Each hosted MintChip is assigned a unique SSL client-authentication certificate and a key, distributed in the form of password-protected PKCS-12 files (.p12). These credentials must be installed on the client device prior to accessing any of the hosted services including the Online Demo applications - the Merchant and the Broker Web sites. Installation of the client certificates is device (platform) specific. Also, it may depend on the application or the browser used to access the Remote MintChip.

Please visit the following links to find more information on how to install a client certificate on your platform:

Windows PC: http://technet.microsoft.com/en-us/library/cc754489.aspx

Firefox on Windows: http://www.onlinehowto.net/install-ssl-certificate-in-firefox/784

iPhone: http://images.apple.com/iphone/business/docs/iPhone_Digital_Certificates.pdf

BlackBerry: http://btsc.webapps.blackberry.com/btsc/viewdocument.do?noCount=true&externalId=KB13492&sliceId=1&dialogID=77551987&cmd=displayKC&docType=kc&stateId=0+0+77553914&ViewedDocsListHelper=com.kanisa.apps.common.BaseViewedDocsListHelperImpl

Android smart phones do not support client certificate authentication with the default Web browser at the time of this writing. Though, the certificates can be used with Firefox for Android (https://play.google.com/store/apps/details?id=org.mozilla.firefox&hl=en) that has the Cert Manager addon (http://handheld.softpedia.com/get/Security/Utilities/Cert-Manager-Firefox-Addon-128066.shtml) installed.