API management

The API Management service controls the access to the Ingenico APIs. Once you have signed the partnership agreement, you have subscribed to an application profile including the subscription to Ingenico APIs. Subscription enables you to receive an initial token and be authenticated to invoke the APIs. This token will permit you to request a usage token the API Management service available on the Ingenico terminal. You can use the usage token to invoke all APIs that you subscribe to using that same application.

Overview

Ingenico provides an initial token to application developers. One initial token is dedicated to one application and is generated for one unique application profile.

Application profiles

Ingenico is defining Application Profiles which include several Sets of APIs, uniquely identified by an ID.

Several APIs are included in each Application Profile, that can be proposed to ISVs, third party developers, partners or regions. The API Management service currently supports 4 Application Profiles:

3 commerce profiles: entry, medium, fully featured. Applications with this profile can start payment transactions
1 loyalty profile: for Applications that deliver loyalty services but do not need to process payments

Application Profiles	Description	Ingenico API packages : "com.ingenico.sdk."
commerceEntry	Entry level commerce APIs for Partners requesting a simple and straightforward transaction integration	transaction / terminal
commerceMedium	Advanced features with basket management and customer facing screens use cases	transaction / terminal / customerscreen (basket)
commerceFullyFeatured	All APIs included	transaction / terminal / customerscreen (basket) / accessories (cashdrawer) / buzzer
loyalty	API set focusing on Loyalty only partners (not using transactions): Buzzer, printer features...	terminal / customerscreen / accessories (cashdrawer) / buzzer

Modules

Three different Ingenico modules are involved in the API Management process:

"API Management Server" (cloud based service)
"Ingenico-Service" (application inside the Android ROM)
"API Access Control" secured module (sits in the secured payment module)

API management server

provides initial tokens to business application developers further to signature of the partnership agreement
provides usage token to "Ingenico-Service" once requested by the application with the initial token

Ingenico-Service

knows API Management Server URL
exposes a "subscribe" API to Android application. Initial tokens are given as parameter.
requests usage token to the "API Management Server"
sends usage token to the "API Access Control" secured module.

"API Access Control" secured module

validates and stores the usage token
controls APIs access according to the given Application Profile (linked to the usage token)

Token

One initial token is valid for one application, and associated to a unique Application Profile. Using the same initial token with another application on the same device will result in a conflict error and prevent from getting the access rights.

Only one initial token can be used at a time for an application. Requesting a new usage token with the initial token will replace the previous usage token.

One initial token is also specific to one API management server (there are 3 different servers production, pre-production and integration). If need be, for development or test purpose, the API management server address can be set using the Ingenico Service configuration application. The "API Access Control” secured module will recognize tokens from all platforms without any configuration.

Workflow

A call to subscribe is required before the Android application can use the APIs. With this call, the service will:

Request a usage token from the API Management server with the initial token. Each usage token is time-limited and a validity period of 20 days.
Send this usage token to the "API Access Control" secured module
As a result of this, if the credentials are valid, the Android Business application will be granted the right to use the APIs that have been subscribed to. A renewal date is provided. It is the responsibility of the Business Application to renew the token before the expiration of this date. A tolerance of 2 days is planned to cope with any difficulty to proceed with the renewal procedure

Configure the API Management Server

By default, the API Management server in production is configured in the Ingenico terminal.

In case there is a need to configure another API Management Server for testing purpose, we provide an application to add other servers’ url as follows. Open the Ingenico Service application.

On the application screen, click on the "+" button on the bottom right and type the new URL to add.

To enable one of the available servers’ URLs, make a long click in the list then choose "Use this server URL".

Request an initial token from the API Management Server

Initial tokens are generated by the API Management Server:

Once you have signed the partnership agreement, your account is created in the developer portal with your credentials including name, email address, country, Application name and Application Profile. This information is used to provision the API Management Server that will generate an initial token.
The initial token is sent to your email address.

The initial token must be kept secret by the Business Application. For Business Applications to be released commercially, it is suggested to use obfuscation to avoid decompilation.

Use the Ingenico API to subscribe an initial token

See the Javadoc.