×

Nokia In-App Payment Porting Guide

Existing applications can be easily ported from Google In-App Billing to Nokia In-App Payment. The interaction with Nokia In-App Payment enabler component is done through the AIDL interface, which offers a similar development approach to Google In-App Billing API. The differences between method signatures and returned data are covered in this document.

The terminology Nokia In-App Payment uses is different compared to the one used by Google In-App Billing. While Google uses the term SKU, Nokia In-App Payment simply uses the terms Product and Product ID to refer to goods at Nokia Store.

To port a Google In-App Billing application to Nokia In-App Payment application, follow the steps below:

  • Create products to Nokia Store's backend as described in the publishing tool quick guide.
  • Add the Nokia In-App Payment AIDL file.
  • Refactor the application's source code to include the Nokia In-App Payment API.
  • Test the application with Nokia-In App Payment test IDs.

Switching AIDL files

Replacing the AIDL file is the first porting step:

  • Delete the com.android.vending.billing package from your project.
  • Right click the /src folder and select File > New > Package.
  • Type com.nokia.payment.iap.aidl in the package name field when prompted. This will create a src\com\nokia\payment\iap\aidl folder in your project.
  • Copy the file <Android SDK install path>\extras\nokia\nokia_x_services\libs\niap\INokiaIAPService.aidl to the folder created in the previous step.

Adapting application source code

Updating billing permission

Edit the Android manifest file (AndroidManifest.xml) file and add the Nokia In-App Payment permissions equivalent to Google specific permissions.

    <!-- Google In-App Billing permission -->
    <uses-permission android:name="com.android.vending.BILLING" />
    
    <!-- Nokia In-App Payment permission -->
    <uses-permission android:name="com.nokia.payment.BILLING"/>

Connecting to the Nokia In-App Payment service

Change your import statements to point to the correct package:

//import com.android.vending.billing.IInAppBillingService;
import com.nokia.payment.iap.aidl.INokiaIAPService;

Declare Nokia In-App Payment related variables:

// This is the expected SHA1 fingerprint of the enabler in HEX format
private static final String EXPECTED_SHA1_FINGERPRINT = "C476A7D71C4CB92641A699C1F1CAC93CA81E0396";
private static final String ENABLER_PACKAGENAME = "com.nokia.payment.iapenabler";

Modify the bindService() call as follows. For improved security we encourage you to inspect integrity of the Nokia In-App Payment enabler. Integrity can be verified by validating SHA 1 fingerprint. Fingerprint verification should be done before binding to the service. verifyFingreprint() source code can be found from Pepper Farm Simulator sample in Payment.java.

    //mContext.bindService(new Intent("com.android.vending.billing.InAppBillingService.BIND"), mServiceConn, Context.BIND_AUTO_CREATE);

    if (verifyFingreprint()) {
        Intent paymentEnabler = new Intent("com.nokia.payment.iapenabler.InAppBillingService.BIND");
        paymentEnabler.setPackage(ENABLER_PACKAGENAME);
        mContext.bindService(paymentEnabler, this, Context.BIND_AUTO_CREATE);   
    }
    else{
        // Nokia In-App Payment enabler is not available.
    }

Update the mService type to INokiaIAPService:

    //IInAppBillingService mService;
    INokiaIAPService mService;

In the onServiceConnected() callback, called by bindService(), get an instance of INokiaIAPService instead of IInAppBillingService:

    //mService = IInAppBillingService.Stub.asInterface(service);
    mService = INokiaIAPService.Stub.asInterface(service);

After the service has connected successfully, check if billing is supported by isBillingSupported() method call. It shares the same method signature as Google In-App Billing.

    int response = mService.isBillingSupported(3, getPackageName(), ITEM_TYPE_INAPP);

This is a standard way to connect to the service. There are no differences in the returned values and error handling between Nokia In-App Payment and Google In-App Billing.

Setting aliases for product IDs

In case your application logic relies on having product IDs in a certain form, you can use setProductMappings method to set text aliases to numeric product IDs used by Nokia In-App Payment backend. If setProductMappings() has been called, queryBundle bundle argument can be left null in getPurchases() method. Usage of setProductMappings() is optional.

Bundle productMappings = new Bundle(); 
productMappings.putString("1023608", "premium");
productMappings.putString("1023609", "gas");
productMappings.putString("1023610", "infinite_gas");

mService.setProductMappings(3, mContext.getPackageName(), productMappings);

Querying product details

Name of the method which is used to query product details has been changed from getSkuDetails to getProductDetails.

The getProductDetails method utilises the same input parameters as getSkuDetails. Returned response bundle has some minor differences in the returned DETAILS_LIST fields.

In the call, only supported type is "Inapp". Subscriptions are not supported. Product bundle is constructed in the same way for both Nokia In-App Payment and Google In-App Billing.

    ArrayList<String> products = new ArrayList<String>();
    products.add("1023608");
    products.add("1023609");
    products.add("1023610");

Construct a query Bundle using key "ITEM_ID_LIST".

    Bundle querySkus = new Bundle();
    
    //querySkus.putStringArrayList(GET_SKU_DETAILS_ITEM_LIST, skuList);
    //Bundle skuDetails = mService.getSkuDetails(3, mContext.getPackageName(), itemType, querySkus);
    querySkus.putStringArrayList(GET_SKU_DETAILS_ITEM_LIST, products);
    Bundle skuDetails = mService.getProductDetails(3,mContext.getPackageName(), ITEM_TYPE_INAPP, querySkus);

The response bundle is a pair of RESPONSE_CODE and DETAILS_LIST key values, similar to Google In-App Billing. DETAILS_LIST has some additional fields in Nokia In-App Payment API.

The table below compares the responses received from each API:

Google In-App Billing response Nokia In-App Payment response
"title": "Sample Title" "title": "nPay Level 1"
"price": "0,75 €" "price": "$0.99"
"description": "Sample description for product: android.test.purchased." "description": "nPay Reference Level 1"
"productId": "android.test.purchased" "productId": "1023608"
"type": "inapp" "type": "inapp"
- "priceValue": "0.99"
- "shortdescription": "nPay Reference Level 1"
- "taxesIncluded": false
- "currency": "USD"
- "isvalid": true

Detailed description for each of the response fields can be found from the developer guide or the API documentation.

Purchasing products

Purchasing is implemented in the same way for both APIs. Pending intent is queried from service in order for the purchase flow to be initiated.

    Bundle intentBundle = mService.getBuyIntent(3, getPackageName(), productId, ITEM_TYPE_INAPP, "myPayload");

After the purchase flow is completed and the activity exits, onActivityResult() is called. The returned Intent contains the response code and information about the purchase. Purchases are not signed in Nokia In-App Payment API. data is a parameter of onActivityResult(int requestCode, int resultCode, Intent data). "INAPP_DATA_SIGNATURE" key is not present in Intent extras. Please comment out any signature verification from your application.

    int responseCode = data.getIntExtra("RESPONSE_CODE", 0);            
    String purchaseDataJson = data.getStringExtra("INAPP_PURCHASE_DATA");
    //String dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE");

INAPP_PURCHASE_DATA contains all the subsets of fields that Google provides. purchaseTime and purchaseState are not used in Nokia In-App Payment.

The following table summarises the returned INAPP_PURCHASE_DATA fields.

Google In-App Billing Nokia In-App Payment
"packageName": "com.example.aidliab" "packageName": "com.example.aidliap"
"orderId": "transactionId.android.test.purchased" "orderId": "NPAY_PGW_TEST_TXN_2222"
"productId": "android.test.purchased" "productId": "1023608"
"developerPayload": "myPayload" "developerPayload": "myPayload"
"purchaseToken": "inapp:com.example.aidliab:android.test.purchased" "purchaseToken": "XDd333xk38s"
"purchaseTime": 0 -
"purchaseState": 0 -

Detailed description of the returned fields can be found in the Developer's Guide.

Querying purchased items

Nokia In-App Payment API supports querying previously purchased products.

Unless setProductMappings method has been used, a list of products whose ownership needs to be checked should be passed as an argument to getPurchases(). This is an additional argument when compared to Google In-App Billing API.

    String continueToken = null;
    //Bundle ownedItems = mService.getPurchases(3, getPackageName(), ITEM_TYPE_INAPP, continueToken);

A list of product IDs can be created as follows:

    ArrayList<String> products = new ArrayList<String>();
    products.add("1023608");
    products.add("1023609");
    products.add("1023610");

A query Bundle can be created by using key "ITEM_ID_LIST".

    Bundle queryBundle = new Bundle();
    queryBundle.putStringArrayList("ITEM_ID_LIST", products);

The Bundle needs to be passed to getPurchases() method, unless product ID aliases have been set.

    Bundle ownedItems = mService.getPurchases(3, mContext.getPackageName(), ITEM_TYPE_INAPP, queryBundle, continueToken);

As with the purchase response, Nokia In-App Payment API does not return signatures for purchases. Please comment out any response signature verification checks from the getPurchases() response handler.

    ArrayList<String> ownedProducts = ownedItems.getStringArrayList("INAPP_PURCHASE_ITEM_LIST");
    ArrayList<String> purchaseDataList = ownedItems.getStringArrayList("INAPP_PURCHASE_DATA_LIST");
    //ArrayList<String> purchaseSignatureList = ownedItems.getStringArrayList("RESPONSE_INAPP_SIGNATURE_LIST");

The following table compares the fields for a single product found in INAPP_PURCHASE_DATA_LIST between Google In-App Billing and Nokia In-App Payment.

Google In-App Billing Nokia In-App Payment
"productId": "android.test.purchased" "productId": "1023608"
"developerPayload": "myPayload" "developerPayload": ""
"purchaseToken": "inapp:com.example.aidliab:android.test.purchased" "purchaseToken": "XDd333xk38s"
"packageName": "com.example.aidliab"  
"orderId": "transactionId.android.test.purchased"  
"purchaseTime": 0  
"purchaseState": 0  

Please note, Nokia In-App Payment API does not return developerPayload as part of getPurchases() response.

Detailed description for the returned fields can be found in the Developer's Guide.

Consuming a purchase

Consuming a purchase in Nokia In-App Payment requires a product ID in addition to a purchase token.

    //int response = mService.consumePurchase(3, mContext.getPackageName(), token);
    int response = mService.consumePurchase(3, mContext.getPackageName(), sku, token);

The response code is handled in the same way as in Google In-App Billing.

Video: Porting to Nokia In-App Payment

The media player is loading...

Testing In-App Purchases

The in-app purchase flow can be tested with preconfigured test IDs. Complete list of IDs can be found in the Developer's Guide. Nokia In-App Payment API does not utilise testing accounts like Google In-App billing. When ready to publish, replace the testing ID with the actual production ID, obtained through Nokia Store. Please remember to perform a final testing round before publishing the application.


Last updated 12 August 2014

Back to top

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×