In-App – API


This chapter would provide a brief overview to the in-app purchasing API guide.


In-app purchase is an increasingly popular form of application monetization which enables application users to download applications free of charge and purchase additional features while running and utilizing the application.

Some examples of the types of purchases the applications can provide are as follows.

  • Subscription to content; like in an online magazine with monthly content updates.
  • Consumable items; for an example pay and buy coins to spend in a gaming application.
  • A permanent purchase to unlock vital features of the application; for instance, the Save function in a photo editing application might be disabled until you’ve paid an in-app fee, so that users can test the application before they decide if it’s worth the price.

In-App Purchase Applications

Hsenid Mobile Solutions provides application developers with the SDK for developing applications. The SDK will contain the library/jar facilitating in-app purchase calls. The in-app application developer can directly call the methods available in iap-android-sdk.jar without worrying about managing charging calls.

Applications which have implemented methods from iap-android-sdk.jar have the capability to connect to in-app Purchase Server (which fires CAAS requests to SDP) via App Store and submit CAAS requests to SDP.


Figure 1.1

In-App Purchase Applications

Once provisioning the developed application in Cloud TAP (SDP), the developer will have to configure the following fields in order to enable in-app purchasing support.

Allowed Host Addresses: The application developer should configure the host address of the in-app purchasing server in this field available in the ‘Basic Configurations’ pane.

Allow In App Purchasing Requests: This should be selected from the ‘Allowed Payment Instruments’ list -CAAS SLA Configuration, to use In App Purchasing requests.

In-app Android SDK

The iap-android-sdk.jar which is bundled with the 3rd party application will be available in the user’s mobile device along with the application download, which means the 3rd party in-app application has implemented methods from the iap-android-sdk.jar. This jar file provides the capability to connect to in-app purchase server (which fires CAAS requests to SDP) via App Store (which is installed in client’s mobile device).

The Application Key

When provisioning an in-app purchase application in SDP, after selecting the in-app purchase NCS and applying application for approval after completing the application provisioning form, the application key will be generated by the in-app purchase server and displayed in a pop up window. That key will be used for authentication when application connects to in-app purchase server.

Things to import

  1. InAppChargingRequest: The Object that contains all relevant parameters related to in-app purchase as attributes. While request is created from client’s device, these parameters will be set and application can send it to server to process.
  2. InAppResponse: TThe Object that contains the response parameters as attributes. This will be created by in-app server while processing InAppRequest and send back. The application can then get it and check the transaction status and details.
  3. InAppChargingResponse: The extended version of InAppResponse, can be created by casting InAppResponse. This has additional response parameters specific to charging like referenceId, internalTrxId.
  4. InAppServiceConnection: An Android service connection object used to connect your application with AppStore. The request will be transferred via InAppServiceConnection.
  5. InAppServiceListener: A Listener object which in-app server notify a response to a listening android application.
  6. InAppServiceConnectionFactory: Factory object to create new InAppServiceConnection.
  7. InAppRequestFactory: Factory object to create new InAppChargingRequest.

Following code snippet depicts a set of sample in- app purchase import lines.

Creating a Connection

  1. There are two modes of connection including the simulator connection which can be used by the developer to test applications without connecting to in-app server and the in-app server connection which can be used once the testing completed and the application is ready to publish.

    To make this mode switching easy, the SDK provides two ways of creating the connection.

    1. If you get InAppServiceConnection using “createSimulationConnection” as explained in 3.1, all the works you do following will then communicate with the simulator.
    2. If you get InAppServiceConnection using “createConnection” as explained in 3.2 all the works you do following will communicate with the production in-app server and starts payments with consumer’s payment instruments.

Working with the Simulator

To start development with In-App purchase, you have a simulator which acts like the App Store and responds to your in-app requests. To communicate with this simulator you need an InAppServiceConnection object for simulation. The static method createSimulationConnection of InAppServiceConnectionFactory will return InAppServiceConnection. For this you have to pass your Android Activity as a parameter, so that when the transaction is simulated, the simulator will call back the activity, with a simulated response.

Following code snippet depicts a sample InAppServiceConnection creation for Simulation.

Working with the In-app Server

Once you are successful with testing your in-app request with the simulator, then it’s time to start communicating with In-App Server via App Store. To do this, you need an InAppServiceConnection object, created by the static method createConnection of InAppServiceConnectionFactory. For this you have to pass your Android Activity as a parameter, so that when the transaction is processed, the App Store will call back the activity with In-App Server’s response.

Following code snippet depicts a sample InAppServiceConnection creation.

Creating an InAppChargingRequest

The InAppRequestFactory class has the static method createChargingRequest, to create an InAppChargingRequest. Following are the parameters which should be given while creating it.

In-app charging request parameters are as follows.

Parameter Name Description String
applicationId Used to identify the application. This is a unique identifier generated by the SDP when provisioning an application. String(32)
applicationDisplayName Name of the application using the services String
applicationKey This is the transaction ID generated by the application to map the request with the response. This is needed to avoid any conflicts when SP inquires about a transaction. String(32)
externalTrxId Name of the item purchased or consumed by the consumer. String(32)
itemName Description of the item purchased by the consumer. String(64)
itemDescription Amount to be charging for the item purchased. String
amount The currency of the amount. String(3)
currency No payment Instruments capable to do this purchase. Transaction Successful

Following depicts a sample InAppRequest creation.

Sending the Request

To send a created in-app Request, just use InAppServiceConnection’s sendRequest() method. The process of sending an in-app Request is an asynchronous call to in-app server. Which means that, the sendRequest() method triggers the process in In-app Server, and immediately return void. When the purchase is completed, the server will call you back using onInAppResponse() method (Please refer chapter 6 for explanation on onInAppResponse method).

Note: An InAppServiceConnection can send only one request at a time. Please refer chapter 8 for more details.

Following code snippet depicts sending an InAppChargingRequest.

Implementing InAppServiceListener and the ‘onInAppResponse’ call-back method

The communication between your application and in-app server is done through AppStore asynchronously. To do that, the application which requires in-app purchasing should have to have an android activity that implements the InAppServiceListener interface. This requires your activity to override ‘onInAppResponse’ call back method.

This ‘nInAppResponse’ call back method will be called by in-app server when purchasing is completed. Application can process next steps by checking InAppResponse (Refer chapter 7 for the explanation on InAppResponse) status from this method.

Getting call back through onInAppResponse

Receiving the InAppResponse

InAppResponse object will be generated by in-app server while processing an InAppRequest and send back to the caller activity using the asynchronous “onInAppResponse” call back method. Following are the parameters which will be available in an InAppChargingResponse.

Following depicts the parameters for in-app Charging Response.

Parameter Name Description String
externalTrxId This is the transaction ID generated by the application to map the request with the response. String
timeStamp The response generated time, in ISO8601 format, like 2014-03-21T00:47:06+00:00 String
statusCode In-app Purchase status, explained in Response Status Codes section String
statusDetail In-app Purchase status description, explained in Response Status Codes section String
internalTrxId Internal Transaction ID generated by the Payment Gateway for the transaction. This is unique per transaction. String
referenceId Unique number generated by the external system for the payment request. String