txtNation Android Billing Library

This document is intended to provide an overview of the txtNation Android in-app billing Library (TAL) and ways in which it may be integrated to a developer's Android application.

See:
          Description

Packages
com.txtnation.android  

 

This document is intended to provide an overview of the txtNation Android in-app billing Library (TAL) and ways in which it may be integrated to a developer's Android application. The TAL is a self-contained Java Archive (JAR) file that can be included in the classpath of your Android application. The TAL allows Android application developers to charge mobile users through their mobile phone accounts. The TAL was designed to minimise the integration process as well as the billing data held by the developer while not compromising the library’s seamless user experience.

Subscription and One-off Payments

TAL supports one-off payments as well as subscription payments. As the names imply, for one-off payments, the TAL will bill the user for a particular product in one transaction and communicate back to the developer's app and/or server web-service with billing confirmations. The subscription payment requires the user to enter a contract authorising recurring payments by making the first transaction. All subsequent transactions will be scheduled and billed at the subscription interval by the txtNation Billing System. Billing notifications for recurring subscription transactions are delivered only to the developer’s server via a web-service.

There are two types of subscription payments:-

  1. txtNation managed subscription payment
  2. Client managed subscription payments

For txtNation managed subscriptions, the integration is as simple as one-off payment integration and exactly follows the same steps; the txtNation subscriptions engine subscribes users and triggers the recurring subscription transactions at the subscribed payment intervals.

The Client-managed subscriptions type allow the client to retain scheduling control of subscriptions within their subscriptions engine and notifies txtNation’s billing system when to bill the user. This type of subscription requires a custom integration with the developer's existing subscription engine. However, developers still have to integrate to the TAL as normal.

Integration

To fully integrate with the txtNation Billing System for one-off payments, the client first needs to integrate on the Client-side by including the TAL in the Android application’s classpath. Secondly, there is a Server-side integration that involves implementing our server-to-server notification API to receive billing status notifications.

This document just focuses on the client-side integration for both subscription and one-off payments. The client-side integration is a four step process:-

  1. Include the TAL.jar file on your Android project's class path
  2. Provide a Payment activity (if you don't have one already) and implement all the callback methods of this Interface com.txtnation.android.PaymentListener (see the sample Eclipse Project named TC_Sample)
  3. Add few permission elements and some generic attributes to the AndroidManifest.xml file of your application.
  4. Use the com.txtnation.android.BillingManger to initiate the transaction (see the sample Eclipse Project named TC_Sample)

Products and Account setup

For each new Android application that requires a new TAL integration, we will setup a new account on the txtNation Billing System, which will provide you with a unique Account ID (accountId) to identify that particular Android application. txtNation will also setup and manage a seperate list of products for each country on your account. Products represent the virtual goods that your application or game is selling. So attributes of a product include Product Name (productName), Price (price), Currency (currency), Units (units) - i.e 30 credits, 3 Months subscrption) - etc. The TAL was designed to hide away this product management complexity from the devloper. This requires a one-time server-side setup

Displaying the Product Selection Screen

ONE STEP BILLING

The TAL can display the appropriate product selection screens (price selection screen) for each country, take selection from users, and display confirmation and notification screens whilst handling regulatory requirements, internationalisation, etc. With this approach, the client needs only to initiate payment by passing the accountId only once and finally, the txtNation Billing System will notify the application and/or the server web-service the outcome of the billing transaction. txtNation's terminology for this kind of setup is 'ONE STEP BILLING'.

TWO STEP BILLING

However, if there is a requirement to display the product selection screens within the client application, outside of the TAL, a flag can be set to indicate this to the TAL, which will then silently return the list of products available for the user's country on your account and not display the price selection screen. The client application will therefore take the price selection from the user and pass the selected product back to the TAL. txtNation's terminology for this kind of setup is called 'TWO STEP BILLING'. It is two steps because first the application must initiate the payment, then the TAL accepts that and returns a list of products to the client application. Once the client application takes the product selection from the user, it calls the TAL again to request billing for the purchase of the selected product.

Testing the Integration

After you have completed the Integration, you can start testing your integration using our testing environments. TAL supports three types of Environment MODEs:-
  1. com.txtnation.android.BillingManger.Environment.LOCAL
  2. com.txtnation.android.BillingManger.Environment.TEST
  3. com.txtnation.android.BillingManger.Enviroment.PRODUCTION

  1. Environment.LOCAL allows developers to test the integration without connecting to txtNation's billing servers. It retrieves products and account configuration information from a sandbox server embedded into the txtNation Android Library (TAL). This is the first stage of integration.
  2. Environment.TEST allows developers to test the integration with txtNations Test server which is a clone of the Production server. To test the integration on the Test Platform, the developer will need a unique account and products setup. This is the second stage of integration.
  3. Enviroment.PRODUCTION allows developers to connect to the production platform. This is the default behaviour if the Environment MODE is not set. Similarly, when using this mode the developer will need prior Account and Product setup for the application. This is the final stage of integration before going live.