In-App Billing

From txtNation Wiki
Jump to: navigation, search

Contents

Introduction

Please contact txtNation business development team, before attempting to follow this integration guide. Email: sales@txtnation.com or +44 (0)1752 484333 switchboard option 2

Thank you for choosing txtNation to be your Android “in-app” billing solutions provider. This single page contains everything you need to know in order to be able to quickly and painlessly integrate our SDK into your application.

It is split into three main parts,

  1. Overview : a rough explanation of the various parts of the service and a gentle introduction to some necessary terminology.
  2. Client-Side Integration :: this covers what you need to do in order to integrate the SDK into your Android project and how to make it all work for you. You can either let the library do all the work displaying everything or you can do it yourself if you have a need for customizing how it looks, maybe to preserve the user experience of your game for example.
  3. Server-Side Integration :: this explains how to create a script on the server that will receive billing notification messages from txtNation's servers when a billing transaction SUCCEEDS or FAILS . This is the final integration step.

Hopefully you will find each section clear and information but should you have any questions at all then please don't hesitate to contact us, we are always glad to help and pleased to know when our clients are getting things done. The email address for any problems is: sdk-help@txtnation.com

Also, if you think that you have any ideas or suggestions that may help to improve this documentation then please feel free to contact us using the following email address: sdk-help@txtnation.com

Other Documentation & Resources

If you are a developer then there are some other pages that you should read. They will explain to you in more detail what the process is supposed to look like and also how to use two instances of the Android emulator to simulate a premium SMS message being sent to your application with a confirmation code to complete the sequence. This means that you can perform testing and still not need a real server nor a PSMS service until later in the integration stage.

  1. In-App Dialog Sequence
  2. Using Two Android Emulators
  3. Download the complete SDK
  4. Unpacking and using the SDK

Overview

This document is intended to provide an overview of the txtNation Android in-application 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 class-path of your Android application. The TAL allows Android application developers to charge mobile users through their mobile phone accounts. The TAL was designed to minimize 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 authorizing 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 payments
  2. Client managed subscription payments

For txtNation managed subscriptions, the integration is as simple as the one-off payment integration and follows exactly 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 allows 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 will have to integrate to the TAL as normal.

Integration

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

Subscription payments integration can be achieved by following all the steps explained in one-off payments integration plus one more API implementation (The Re-billing API). This API allows clients to send recurring billing requests.

The client-side integration for both Subscription and One-off payments 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.BillingManager to initiate the transaction (see the sample Eclipse Project named TC_Sample)

The server side integration involves implementing two APIs.

  1. The Notification API for both Subscription and One-off Payments.
  2. The Re-billing API for only Subscription payments where clients manages subscriptions. If txtNation manages the subscriptions, clients do not need to implement this integration.

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 a particular Android application. txtNation will also setup and manage a separate 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 subscription) - etc. The TAL was designed to hide this product management complexity from the developer. This requires a one-time server-side setup.

Display the Product Selection Screen

ONE STEP BILLING

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

txtNation's terminology for this setup is 'ONE STEP BILLING'.

TWO STEP BILLING

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'. The first step involves the application initiating the payment. The TAL then returns a list of products to the client application. After the client application takes the product selection from the user, the second step involves the TAL requesting billing for the purchase of the selected product.

Testing the Integration

After you have completed the Integration, you can start testing the 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.BillingManager.Enviroment.PRODUCTION

The various steps are as follows:

  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 txtNation’s 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 product setup. This is the second stage of integration.
  3. Environment.PRODUCTION allows developers to connect to the production platform. This is the default behavior 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.

Unpacking the SDK

This section will cover what is contained in the txtNation_IABSDK.zip file, how to deal with it and what the various folders contain to help you get started and complete a successful integration with your mobile product.

The rest of this document assumes that you are using Eclipse ADT. If you are not then may have to replace certain steps with whatever makes sense for your chosen environment, for example, you may be using IntelliJ or emacs!

Extract the contents

Client-side integration

Overview

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 PaymentActivity class (if you don't have one already) and implement all the callback methods of the com.txtnation.android.PaymentListener interface.
  3. Add a few permission elements and some generic attributes to the AndroidManifest.xml file of your Android application if they don’t already exist. The Manifest example below shows the minimum requirements for the application to work.
  4. Use the com.txtnation.android.BillingManger class to initiate the transaction (see the sample Eclipse Project named GC_Client_Sample and the JavaDoc for BillingManager Class).

Integration Steps

Each of the above steps are expanded below.

  1. Include the TAL.jar file on your Android project's class path. The following are instructions to add the TAL.jar to your application’s build path using Eclipse.

    1. In the Package Explorer panel, right-click on your project and select Properties.
    2. Select Java Build Path, then the Libraries tab.
    3. Click on the Add External JARS... button and select the TAL.jar file.

  2. Provide a PaymentActivity class (if you don't have one already) and implement all the callback methods of the com.txtnation.android.PaymentListener interface.
    class YourPaymentActivity extends Activity implements PaymentListener
    For more information see the sample Eclipse Project named GC_Client_Sample and the JavaDoc PaymentListener Interface.

  3. Add a few permission elements and some generic attributes to the AndroidManifest.xml file of your application if they don’t already exist. The Manifest example below shows the minimum requirements for the application to work.
<manifest ... >
 
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.READ_PHONE_STATE" />
  <uses-permission android:name="android.permission.RECEIVE_SMS" />
  <uses-permission android:name="android.permission.SEND_SMS" />
  <uses-permission android:name="android.permission.READ_SMS" />
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
 
  <!-- This is needed by Android 1.6 to enable WiFi enabling and disabling -->
  <uses-permission android:name="android.permission.UPDATE_DEVICE_STATS"></uses-permission>
  <uses-permission android:name="android.permission.WAKE_LOCK"></uses-permission>
 
  <application .. >
    <activity android:name="YourPaymentActivity" android:screenOrientation="portrait">
      ...
    </activity>
  </application>
</manifest>

Please note that the Android screen orientation attribute must be set to portrait. This does not mean that your entire application has to be portrait! It merely insists that the activity issuing the in-application billing call must be locked to portrait mode.

The Billing Manager class

Use the com.txtnation.android.BillingManager class to initiate the transaction. See the sample Eclipse Project name TN_Sample and JavaDoc Billing Manager class for more information.

The TAL gives you the choice of displaying the price selection screen within your application or to have the TAL display it for you. The two ways of handling price selection are described below but for more information please review the JavaDoc Overview/Summary.

One-step Billing

In this mode the TAL.jar library code will manage the display and selection of something that the user can purchase or subscribe to.

To use the library in this mode requires four simple steps:

  1. Instantiate the BillingManager class
  2. Set the operating evironment for the instance
  3. Register your callback Activity with the manager
  4. Initiate the transaction

Instantiate the BillingManager class

Instantiate the BillingManager passing your PaymentActivity as the first parameter and a Handler generated within your PaymentActivity as the second parameter.

billingManager = new BillingManager(YourPaymentActivity.this, mHandler);

As is normal for Android applications, background threads cannot interact with the main UI thread and so a Handler instance is given to the billing manager so that it can launch various interface pop-ups and dialogs when it needs to do so.

Set the operating environment for the instance

The "environment" is what determines how the library operates once a transaction has been initiated as shown in the previous step. There are three modes of operation referred to as "local", "test" and "production".

  • Environment.LOCAL This mode is the first step that you should use when integrating the SDK with your code.
    billingManager.setEnvironment(Environment.LOCAL);
    It is a purely internal form of operation, no data leaves the phone and instead the library uses a small and efficient internal server to pretend that a transaction is being performed. This allows you to see the various selection and confirmation screens in operation without needing any other resources.
  • Environment.TEST This is the second step, this does communicate with the servers but only in a "test" mode.
    billingManager.setEnvironment(Environment.TEST);
  • Environment.PRODUCTION This is for "go-live" code that has been developed and proven to work in LOCAL and TEST modes. Using this mode requires a real account to have been configured prior to operations.
    billingManager.setEnvironment(Environment.PRODUCTION);

Register your callback Activity with the manager

Having instructed the library of its mode of operation you now need to register your callback handler. Typically this is the Activity that has implemented the com.txtnation.PaymentListener interface and is locked to portrait mode.

billingManager.registerPaymentListener(YourPaymentActivity.this);

Initiate the transaction

Initiate the transaction using the following required parameters:

boolean bPaymentPending = billingManager.beginPayment(
    accountId,
    endUserId,
    clientAppVersion,
    isOneStepBilling
);
  • accountId – txtNation provided unique identifier for your application
  • endUserId – A unique Identifier (like a transaction or reference ID) that will be returned to your application and server at the end of the transaction. Using a duplicate identifier will cause the transaction to fail almost immediately. It is important for auditing purposes that each transaction has a unique identifying value.
  • clientAppVersion – The version identifier for your application, there are no hard and fast rules other than that it helps you track which version of your code is currently operating on the device.
  • isOneStepBilling – If set to to true the BillingManager displays product (price) selection screens, otherwise your application must return the products (prices) and your application must handle the selection screens.

The return variable is a boolean which we have called bPaymentPending. You are of course free to call it whatever you like. It will be true if the billing manager starts the process with no errors and then you can use this flag internally to ensure that you don't start another payment until the current one has completed.

The response to step 4. is a list of products that have been configured for the application user's country. Your application should display the list as "price options" to the user and then take the selection made from the list. This selection is then passed to the TAL as the code sample below shows:

billingManager.purchaseProduct(selectedProduct);

This will become clearer if you inspect the sample projects as you can then see the above line in its full operational context.

The one-step billing process can be summarized as shown in this diagram:

onestepmessageflow.png

Note: The onPaymentStateChanged callback is only for informative purposes and therefore can be ignored if you do not intend to handle the payment progress updates.

Two-step Billing

To use two-step billing requires that your application implement the following five steps:

  1. Instantiate a BillingManager
  2. Set the operating environment
  3. Register you PaymentActivity callback handler
  4. Initiate the transaction via the BillingManager
  5. Call the purchaseProduct method with the user's selected product

The above steps will now be explained:

Instantiate the BillingManager class

Instantiate the BillingManager passing your PaymentActivity as the first parameter and a Handler generated within your PaymentActivity as the second parameter.

billingManager = new BillingManager(YourPaymentActivity.this, mHandler);

As is normal for Android applications, background threads cannot interact with the main UI thread and so a Handler instance is given to the billing manager so that it can launch various interface pop-ups and dialogs when it needs to do so.

Set the operating environment for the instance

The "environment" is what determines how the library operates once a transaction has been initiated as shown in the previous step. There are three modes of operation referred to as "local", "test" and "production".

  • Environment.LOCAL This mode is the first step that you should use when integrating the SDK with your code.
    billingManager.setEnvironment(Environment.LOCAL);
    It is a purely internal form of operation, no data leaves the phone and instead the library uses a small and efficient internal server to pretend that a transaction is being performed. This allows you to see the various selection and confirmation screens in operation without needing any other resources.
  • Environment.TEST This is the second step, this does communicate with the servers but only in a "test" mode.
    billingManager.setEnvironment(Environment.TEST);
  • Environment.PRODUCTION This is for "go-live" code that has been developed and proven to work in LOCAL and TEST modes. Using this mode requires a real account to have been configured prior to operations.
    billingManager.setEnvironment(Environment.PRODUCTION);

Register your callback Activity with the manager

Having instructed the library of its mode of operation you now need to register your callback handler. Typically this is the Activity that has implemented the com.txtnation.PaymentListener interface and is locked to portrait mode.

billingManager.registerPaymentListener(YourPaymentActivity.this);

Initiate the transaction

Initiate the transaction using the following required parameters:

boolean bPaymentPending = billingManager.beginPayment(

accountId,

endUserId,

clientAppVersion,

isOneStepBilling);

  • accountId – txtNation provided unique identifier for your application
  • endUserId – A unique Identifier (like a transaction or reference ID) that will be returned to your application and server at the end of the transaction. Using a duplicate identifier will cause the transaction to fail almost immediately. It is important for auditing purposes that each transaction has a unique identifying value.
  • clientAppVersion – The version identifier for your application, there are no hard and fast rules other than that it helps you track which version of your code is currently operating on the device.
  • isOneStepBilling – If set to to true the BillingManager displays product (price) selection screens, otherwise your application must return the products (prices) and your application must handle the selection screens.

The return variable is a boolean which we have called bPaymentPending. You are of course free to call it whatever you like. It will be true if the billing manager starts the process with no errors and then you can use this flag internally to ensure that you don't start another payment until the current one has completed.

The two-step billing process can be summarized as shown in this diagram:

twostepmessageflow.png

Note: The onPaymentStateChanged callback is only for informative purposes and therefore can be ignored if you do not intend to handle the payment progress updates.

The response to step 4. is a list of products that have been configured for the application user's country. Your application should display the list as "price options" to the user and then take the selection made from the list. This selection is then passed to the TAL as the code sample below shows:

billingManager.purchaseProduct(selectedProduct);

This will become clearer if you inspect the sample projects as you can then see the above line in its full operational context.

Call purchaseProduct to confirm the purchase.

The response to step 4. would be a list of products configured for the User’s country. Your application should display the list as price options to the User, and take the User’s selected product. This selection will then be passed to the TAL as the code sample below shows:

billingManager.purchaseProduct(selectedProduct);

Server-side integration

After successful client-side integration you may need to implement up to six simple APIs:

  1. Billing Notification API
  2. Subscription Re-billing API
  3. Subscription Cancellation APIs
    a. SMS Cancellation API
    b. IN-APP Cancellation API
  4. Subscription Reminders API
  5. Subscription Information API

If you do not have a subscription engine of your own, you only need to implement one API (the Billing Notification API) and can ignore the rest of the APIs.

To make this integration as easy as possible for you, we have included a sample Java-based Eclipse RESTful web service project named tn_sample_server as part of the SDK.

Currently this sample project is only available in Java although any other server language such as PHP can be used; after all you are only having to deal with the receipt of an HTTP POST message from the server.

We will now cover the above API calls in more detail. If you only p lan to use the in-app payment for purchases rather than subscription based content then you only need to implement the first function.

Billing Notification API

Both Subscription and One-off Payment accounts must implement this API. txtNation servers will call your billing notification script as soon as a billing notification is received from the user’s mobile network operator. Client systems should accept this request and act on it according to the transaction status. If the transaction status is BILLED, the client should credit/deliver services to the user’s online account, otherwise the client should mark the transaction as FAILED in its system.

Here is a typical request using the PLAIN mode:

http://clients-notification-urls?accountId=5557331&endUserId=testUser1&msisdn=447554090256&imsi=234159089455967&subscriptionTriggerId=240
&billingStatus=FAILED&price=0.500&productId=8&operatorName=TMOBILE_UK&currency=GBP&transactionId=testUser1hs=b0c148381420e72a766e6289c846da3f

The fields to the request that may be present are described here:

PARAMETER DESCRIPTION EXAMPLE
accountId txtNation provided unique Identifier for the client’s Android Application accounted=5557331
endUserId A unique Identifier for the end user of the current transaction. This ID exists in the client’s system. endUserId=TestUserId
msisdn The mobile number of the end user. The number of the mobile being charged in international format msisdn=447554090256
Imsi A unique Identifier that Identifies the SIM of the end user as well as their country and network operators. imsi=234159089455967
subscriptionTriggerId This is only relevant for Subscriptions. This ID is the request ID (the OPT IN for subscription). All recurring billing requests must reference a valid subscriptionTriggerId. subscriptionTriggerId=240
billingStatus Current transaction’s billing status. Valid values are BILLEDand FAILED. BILLED indicates that the user has been charged. BillingStatus=BILLED
price Amount charged or Failed to be charged to the user’s account. If the billingStatus is BILLED, the amount has been charged. Otherwise, it means we failed to charge that amount. price=0.50
currency Client’s unique transaction Id for this transaction. If no transaction Id has been provided by the client’s system, this parameter is assigned the same value as endUserId. transactionId=ST133433
hs A 32 character security hash generated from the transactionId and the client’s Server-to-Server Hashing Salt (see the Connection Form) hs=b0c148381420e72a766e6289c846da3f
productId A numberic ID of the current product for this transaction. txtNation and the client may agree to synchronise product Ids at the point of account setup or new product setup. productId=8
operatorName Name of the operator. The format is operatorName concatenated with country code. See Appendix A for a full operator list. operatorName=TMOBILE_UK
subscriptionInterval Name of the operator. The format is operatorName concatenated with country code. See Appendix A for a full operator list. operatorName=TMOBILE_UK
subscriptionInterval What measuring unit to use forsubscription (minutes, days etc) subscriptionInterval=DAY (MINUTE,DAY,MONTH)
subscriptionIntervalUnits Number of subscriptionInterval, 7 minutes, 7 days etc subscriptionIntervalUnits=7
isSubscription Is this notification a subscription or one-off payment notification isSubscription=true

If your system accepts and processes the request, you should return some kind of reference ID that may be useful for customer service enquiries, otherwise return the value of the transactionId parameter.

Subscription Re-billing API

This API should only be called by Subscription clients who manage their subscriptions. If txtNation manages your subscription you shouldn’t call this API. Clients who manage their subscriptions should take extra care to ensure the subscription engine does not make unauthorised re-billing requests. By calling this API, your platform is asking txtNation’s billing system to start recurring transaction process and charge the user’s account with the subscription amount. To request rebilling, just make an HTTP hit to the re-billing service as shown below.

The URL has been split across a few line for clarity but you should of course make int a single string:

   http://apps.txtnation.com/iab/request.phpiabreq=rebill?accountId=5557331&msisdn=447554090256
    &imsi=234159089455967&subscriptionTriggerId=240&transactionId=NEW_TRANSACTION_ID
    &hs=GENERATED_HASH

Important: the iabreq=rebill must be present and correct. This parameter is the instruction to the server that dictates what operation is being requested by your call. The currently supported values for this parameter are:

  • iabreq : Perform a rebilling request
  • unsubbyacc : Perform a subscription cancellation
  • sendfreereminder : Send a free subscription reminder

Each parameter has the same meaning as its corresponding Billing Notification API parameter. Please note transactionId here must be a unique id that will allow your system to identify this recurring transaction. Once the billing has been performed, the txtNation system will notify your system via the Billing Notification API but this time with the new transaction Id you passed here.

If txtNation billing system accepts the request, you will receive ‘accepted’ as the response of the Re-billing HTTP hit, otherwise, ‘not_accepted’.

404 Errors returned by this service

ERROR DESCRIPTION
missing_account_id Account ID is missing
missing_msisdn_or_imsi Either IMSI or MSISDN is missing. Must provide one of them.
missing_hash Hash string is missing.
missing_subscription_trigger_id No subscription Trigger ID. Return the trigger ID that came with the first Billing Notification.
unidentified_request HTTP Basic Auth has failed
unauthorized IP address is not white-listed
unauthorizedH Hash Strings don’t match.

Subscription Cancellation APIs

There are two methods in which a subscriber may cancel their subscription(s):

  1. Canceling by MSISDN – via ‘STOP’ SMS; and
  1. Canceling by Account – via an in-app cancel button.

SMS Cancellation API

The subscriber is able to cancel any subscriptions attributed to their MSISDN by sending an SMS with the keyword ‘STOP’ to a shortcode. This API allows txtNation to notify you of any subscriber cancellation requests via SMS.

Upon receiving a ‘STOP’ MO to a shortcode, txtNation will trigger a synchronous request to your SMS Cancellation API endpoint with MSISDN, accountId and hash. These parameters have already been defined in the parameters table above. Here’s an example request:

   http://clients-unsubscribe-by-msisdn-urlsaccountId=5557331&msisdn=447554090256&hs=GENERATED_HASH

Request parameters:

PARAMETER DESCRIPTION EXAMPLE
accountId txtNation provided unique Identifier for the client’s Android Application accounted=5557331
msisdn The mobile number of the end user. The number of the mobile being un-subscribed in international format msisdn=447554090256
hs A 32 character security hash generated from the msisdn and the client’s Server-to-Server Hashing Salt (see the Connection Form) hs=b0c148381420e72a766e6289c846da3f

In response to the request, you are expected to unsubscribe all active subscriptions attributed to the MSISDN sent in the request, before compiling a JSON response with the following parameters:

PARAMETER DESCRIPTION EXAMPLE
isMsisdnKnown Boolean value signifying whether the MSISDN sent in the request is known isMsisdnKnown=true
isMsisdnUnsubscribed Boolean value signifying whether the MSISDN sent in the request has been successfully unsubscribed isMsisdnUnsubscribed=true
unsubscribeTicket A unique reference to the current un-subscription. unsubscribeTicket=TK4532565679B
numOfCancelledSubs t is possible that more than one subscription is cancelled as result of this request if this MSISDN has more than 1 subscriptions against it. All subscriptions must be cancelled. Return the number of subscriptions that have been cancelled using this field numOfCancelledSubs=1

Here’s an example of the expected JSON response:

{ "isMsisdnKnown"        : true
, "isMsisdnUnsubscribed" : true
, "unsubscribeTicket"    : "TK4532565679B"
, "numOfCancelledSubs"   : 1 }

Upon receiving a successful un-subscription response, txtNation will send a confirmation SMS to the subscriber.

Review the diagram below for a more detailed flow of this API.

cancellationbysms.png

IN-APP Cancellation API

This API supports subscriber cancellations triggered from a Cancel button or similar within the application itself. In this scenario, the cancellation request is sent from your application directly to your server specifying the clientAccountID. The clientAccountID is a meaningful subscriber ID to you – such as an email address for example. You will then use this to un-subscribe the user and lookup necessary data to pass through to txtNation for un-subscription at our end.

The parameters you will need to send in the request are defined below:

PARAMETER DESCRIPTION EXAMPLE
accountId txtNation provided unique

Identifier for the client’s Android Application

accounted=5557331
msisdn The mobile number of the end user. The number of the mobile being charged in international format msisdn=447554090256
imsi A unique Identifier that Identifies the SIM of the end user as well as their country and network operators. imsi=234159089455967
subscriptionTriggerId This is only relevant for Subscriptions. This ID is the request ID (the OPT IN for subscription). All recurring billing requests must reference a valid subscriptionTriggerId. subscriptionTriggerId=240
unsubscribeTicket A unique reference to the current unsubscription unsubscribeTicket=

TK4532565679B

hs A 32 character security hash generated from the transactionId and the client’s Server-to-Server Hashing Salt (see the Connection Form) hs=b0c148381420e72a766e6289c846da3f

Here’s an example request:

   http://apps.txtnation.com/iab/request.php?iabreq=unsubbyacc
    &accountId=5557331&msisdn=447554090256&imsi=234549290401235
    &subscriptionTriggerId=243&unsubscribeTicket=TK4536562679&hs=GENERATED_HASH

txtNation will then respond with a HTTP 200 Response of either “accepted” or “not_accepted” as described below:

RESPONSE DESCRIPTION
accepted Un-subscription request has been accepted.
not_accepted Un-subscription request has been accepted.

Following an “accepted” response, txtNation will confirm the un-subscription with an SMS to the subscriber.

Review the diagram below for a more detailed flow of this API.

cancellationbyaccount.png

Subscription Reminders API

The fifth and final API allows you to periodically send reminder messages to Subscribers. At the scheduled period, you will send a request to this API supplying the following parameters:

PARAMETER DESCRIPTION EXAMPLE
accountId txtNation provided unique

Identifier for the client’s Android Application

accounted=5557331
msisdn The mobile number of the end user. The number of the mobile being reminded in international format msisdn=447554090256
imsi A unique Identifier that Identifies the SIM of the end user as well as their country and network operators. imsi=234159089455967
subscriptionTriggerId This is only relevant for Subscriptions. This ID is the request ID (the OPT IN for subscription). All recurring billing requests must reference a valid subscriptionTriggerId. subscriptionTriggerId=240
reminderTicket A unique reference to the current reminder reminderTicket=RG4532505629E
hs A 32 character security hash generated from the hs=b0c148381420e72a transactionId and the client’s Server-to-Server Hashing Salt (see the Connection Form) hs=b0c148381420e72a766e6289c846da3f

The API is very similar to the In-App Cancellation API, but not the same, please note the differences. Here’s an example request:

   http://apps.txtnation.com/iab/request.php?iabreq=sendfreereminder
    &accountId=5557331&msisdn=447554090256&imsi=234549290401235
    &subscriptionTriggerId=243 &hs=GENERATED_HASH

txtNation will then respond with a HTTP 200 Response of either “accepted” or “not_accepted” as defined in the In-App Cancellation API above.

Please review the diagram below for a more detailed flow of this API.

freereminder.png

Subscription Information API

This API is only required in some countries like the USA otherwise you may not need to implement it. txtNation will let you know if you require implement this API. The subscriber is able to get subscription information attributed to their MSISDN by sending an SMS with the keyword ‘HELP’ to a shortcode. This API allows txtNation to notify you the subscription information requests from subscribers sending ‘HELP’ SMS messages from their handsets.

Upon receiving a ‘HELP’ MO to a shortcode, txtNation will trigger a synchronous request to your Subscription Information API endpoint with MSISDN, accountId and hash.

Here’s an example request:

   http://clients-get-subscription-info-url?
    accountId=5557331&msisdn=447554090256&hs=GENERATED_HASH

Request Parameters:-

PARAMETER DESCRIPTION EXAMPLE
accountId txtNation provided unique Identifier for the client’s Android Application accounted=5557331
msisdn The mobile number of the end user. The number of the mobile being unsubscribed in international format msisdn=447554090256
hs A 32 character security hash generated from the msisdn and the client’s Server-to-Server Hashing Salt (see the Connection Form) hs=b0c148381420e72a766e6289c846da3f

In response to the request, you are expected to find the details of any subscription against

the MSISDN provided whether it is an active subscription or not before compiling a JSON

response with the following parameters:

PARAMETER DESCRIPTION EXAMPLE
isMsisdnKnown Boolean value signifying whether the MSISDN sent in the request is known to your subscription engine (active or inactive) isMsisdnKnown=true
isSubscriptionActive Boolean value signifying whether the MSISDN sent in the request has an active subscription running. newDate= 1360596393703
renewDate If subscription is active, the date newDate= 1360596393703 of the next re-bill (the next billing cycle date). The format of this field is represented as the "the epoch" date format – the number of milliseconds since January 1, 1970, 00:00:00 GMT imsi=234159089455967
imsi The IMSI for this MSISDN. txtNation passes this IMSI to your subscription Engine at the point subscription start. imsi=234159089455967
subscriptionTriggerId This is only relevant for Subscriptions. This ID is the request ID (the OPT IN for subscription). All recurring billing requests must reference a valid subscriptionTriggerId. subscriptionTriggerId=240

Here’s an example of the expected JSON response:

{ "isMsisdnKnown" :true
, "isSubscriptionActive" :true
, "renewDate" :1360596393703
, "imsi" :"234159089455967"
, "subscriptionTriggerId":"204" }

Upon receiving a successful Subscription Information response, txtNation sends an SMS to the subscriber.

Review the diagram below for a more detailed flow of this API.

helpinfoapi.png

APPENDIX A (UK, Netherlands and German Networks)

NETWORK NAME DESCRIPTION Subscription Maximum
Retry for failed Transaction
TMOBILE_DE T-Mobile Germany 3
VODAFONE_DE Vodafone Germany 4
O2_DE O2 Germany 5
EPLUS_DE 1
O2_UK O2 UK
VODAFONE_UK Vodafone UK
3_UK 3 UK
TMOBILE_UK T-Mobile UK
ORANGE_UK Orange UK


APPENDIX B (UK; Payforit)

This SDK is compatible with Payforit 4.1, requiring all in-app billing purchases to be made through an approved Payforit accredited provider.*

  • This SDK is accredited across all networks in the UK and the Payforit board.
Personal tools