OVERVIEW
The SDK will allow you to easily integrate your application with GlobalCharge, allowing you to bill your users via a one-off transaction or regular subscription transactions.
Our integration is designed to greatly simplify the process of enabling carrier billing inside your Android applications, removing your requirement to integrate directly with individual aggregators and operators in each of the regions you require.
Figure 1: High-level overview of the process.
Your Android Application initiates the payment process to the GlobalCharge SDK.
The GlobalCharge SDK requests the list of products available and configured for your Android Application from the GlobalCharge back-end servers.
The GlobalCharge back-end servers send the relevant list of available and configured products to the GlobalCharge SDK.
The GlobalCharge SDK send the product list to your Android Application.
In your Android Application, your end-user selects the product they wish to purchase.
At this point, The User interface control is passed from your Android application to the GlobalCharge SDK and processing of the payment begins.
Success/failure messaging is presented back to the User interface and control as passed back to your Android Application.
Messaging, in relation to Success/Failure, is sent from the GlobalCharge back-end server to your back end Servers.
Figure 2: Details process flow Diagram.
Client android integration with GlobalCharge Android SDK
1. Introduction:
The GlobalCharge SDK is capable of billing users on a one-off single payment basis and also on a subscription basis. GlobalCharge SDK is an Android library with name *.aar which we will provide you. Your application needs to communicate with this SDK through some API calling; providing necessary parameters inorder to trigger the billing process.
2. Steps:
There is two way of integrating with GlobalCharge SDK in order to trigger the billing.
A. ONE STEP BILLING(Optional, Not required)
B. TWO STEP BILLING
STEP 1:
Add a dependency in your 'app' module (your main application module) build.gradle file to include our SDK file with your android application.
Figure 3: Screenshot Android Development studio
dependencies {
implementation ('com.globalcharge.android:gal:4.5.0')
}
Add a dependency in your 'app' module (your main application module) build.gradle file to include provided .aar file with your android application.
STEP 2:
Create/Provide a class 'YourPaymentActivity' which implements all the callback methods of the
com.globalcharge.android.PaymentListener(An interface in our SDK/*.aar)
class YourPaymentActivity extends Activity implements com.globalcharge.android.PaymentListener
com.globalcharge.android.PaymentListener consists of below methods
void onProductsReceived(List
void onProductSelected(Product var1);
void onCancelled();
void onFailure(String var1);
void onSuccess(int var1);
void onPaymentStateChanged(String var1);
void onSubscriptionCancelSuccess(String var1, String var2, String var3);
void onSubscriptionCancelFailure(String var1, String var2, String var3);
STEP 3:
billingManager = new com.globalcharge.android.BillingManager(YourPaymentActivity.this,mHandler);
Follow the below steps to start a billing transaction
- Instantiate the
com.globalcharge.android.BillingManagerpassing yourPaymentActivityas the first parameter and a Handler generated within yourPaymentActivityas the second parameter.
billingManager.setEnvironment(Environment.LOCAL);
billingManager.setEnvironment(Environment.TEST);
billingManager.setEnvironment(Environment.PRODUCTION);
- Set enviroment; 3 types of environment are available:
LOCAL, TEST, PRODUCTION
billingManager.registerPaymentListener(YourPaymentActivity.this);
- Register
YourPaymentActivity(This class implementsPaymentListener) with the BillingManager as a listener of payment progress. So all the callback method has been implemented in YourPaymentActivity class will receive all callbacks with a transaction’s progress update.
boolean isPaymentBegan = billingManager.beginPayment(accountId, endUserId,clientAppVersion, isOneStepBilling);
- Trigger the billing by calling
'beginPayment'method from BillingManager class.
Method Signature: public boolean beginPayment(long accountID, String endUserId,String clientAppVersion, boolean isOneStepBilling)
| NAME | TYPE | DESCRIPTION | MANDATORY | COMMENTS |
|---|---|---|---|---|
| accountID | long | YES | GlobalCharge will provides your accountID | |
| endUserId | String | A unique Identifier of a transaction (transaction/reference/session ID) that will be returned to your application and server at the end of the transaction | YES | You create this |
| clientAppVersion | String | Version identifier for your application | YES | You create this |
| isOneStepBilling | boolean | If set to true our SDK displays product (price) selection screens, otherwise your application must handle product selection screens where user can select which product they want to purchase | YES | Please always set this to false |
- At this point, you have already triggered the billing and the GlobalCharge SDK should call you back with a list of products(List
) available for your account, on ‘onProductsReceived’ method which you already implemented. - Now you/user should select a single product from the list you have received.
- Call the
'purchaseProduct'method from BillingManager class passing the selected product to complete billing trigger. - Then you will receive callback either
'onSuccess'or'onFailure'method which you have already implemented.
Figure 4: Two-Step Billing flow
Backend Integration
1. Billing Notification pattern
GlobalCharge will notify your server with bellow pattern when a billing transaction is completed, This can be a first-time transaction or a rebill.
Your server(application) should accept this notification and provide the content to the user depending upon whether the
'billingStatus' is BILLED of FAILED
Expected Response: HTTP response 200 and value of any unique reference id such as
endUserId ending with -SUCCESS or -FAILED
Example URL:
First time billing notification:
http://your-notification-url.com?accountId=123&endUserId=testUser1&msisdn=447554090256&imsi=234159089455967&subscriptionTriggerId=240&billingStatus=FAILED&price=0.500&productId=8&operatorName=TMOBILE_UK¤cy=GBP&transaction=testUser1&hs=b0c148381420e72a766e6289c846da3f&subscriptionInterval=DAY&subscriptionIntervalUnits=7&isSubscription=true&countryCode=GB&paymentId=18683083234159177509832-4&billing_type_method=NOT_PROVIDED
Rebill billing notification:
http://your-rebill-notification-url.com?accountId=123&endUserId=testUser1&msisdn=447554090256&imsi=234159089455967&subscriptionTriggerId=240&billingStatus=FAILED&price=0.500&productId=8&operatorName=TMOBILE_UK¤cy=GBP&transaction=testUser1&hs=b0c148381420e72a766e6289c846da3f&subscriptionInterval=DAY&subscriptionIntervalUnits=7&isSubscription=true&countryCode=GB&paymentId=18683083234159177509832-4&billing_type_method=NOT_PROVIDED
| PARAMETER | DESCRIPTION | EXAMPLE |
|---|---|---|
| accountId | GlobalCharge 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 BILLED and FAILED. BILLED indicates that the user has been charged. | BillingStatus=BILLED |
| price | The 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 | The currency of the price above. ISO currency code. | currency=GBP |
| transactionId | 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 numeric ID of the current product for this transaction. GlobalCharge and the client may agree to synchronise product Ids at the point of account setup or new product setup. | productId=8 |
| productId | A numeric ID of the current product for this transaction. GlobalCharge 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 | What measuring unit to use for subscription (minutes, days etc) | subscriptionInterval=DAY (MINUTE,DAY,MONTH) |
| subscriptionInterval Units | Number of subscriptionInterval, 7 minutes, 7 days etc | subscriptionIntervalUnits=7 |
| isSubscription | Is this notification a subscription or one-off payment notification | isSubscription=true |
| countryCode | The two character ISO country code for the transaction | countryCode=NL |
| paymentId | A Unique transaction ID for this notification, this ID should be used to avoid duplicate notifications | paymentId=18683083234159177509832-4 |
| billing_type_method | The billing method used to bill this transaction, sometimes we send Text Message to bill, other times we directly bill users without sending text message, etc Possible values are NOT_PROVIDED, SMART_BILLING, SPLIT_BILLING, DIRECT_BILLING, PSMS_BILLING | billing_type_method=PSMS_BILLING |
2. Subscription Re-billing API
You should call this API only if you managing the subscription for the user. If GlobalCharge or any other party(operator/aggregator) manages your subscription you shouldn’t call this API.
URL to trigger Re-bill:
http://webapps.globalcharge.com:8040/inappservices/rest/payments/rebill?accountId=5557331&msisdn=447554090256&imsi=234159089455967&subscriptionTriggerId=240&transactionId=your_uninque_reference_id&hs=GENERATED_HASH
| PARAMETER | DESCRIPTION | EXAMPLE |
|---|---|---|
| accountID | GlobalCharge provided unique identifier for the client's Android Application. | accountId=5557331 |
| msisdn | The mobile number of the end user. The number of the mobile being charged in international format. | msisdn=4915110088530 |
| imsi | A unique identifier that identifies the SIM of the end user as well as there country code and network operators. | imsi=262011040160966 |
| 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=8810392 |
| transactionId | Client's unique transaction Id for this transaction. If no transactionId is provided by the client's system, this parameter is assigned to 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 |
Once you have triggered the rebill, we will call you back on your re-bill notification URL explained above at section one.
GlobalCharge will return a 200 responce with ‘accepted’ if we receive your trigger or will return the below errors in case of a failure.
| ERROR | DESCRIPTION |
|---|---|
| missing_account_id | Account ID is missing |
| missing_msisdn_or_imsi | Either the IMSI or MSISDN is missing. It is mandatory provide one of them. |
| missing_hash | The Hash string is missing. |
| missing_subscription_trigger_id | No subscription Trigger ID. Return the trigger ID that came with the first Billing Notification. |
| missing_transaction_id | No transaction ID. |
| unidentified_request | HTTP Basic Auth has failed. |
| unauthorized | The IP address is not whitelisted. |
| unauthorizedH | The Hash Strings don’t match. |
3. Subscription Cancellation APIs
There are two methods in which a subscriber may cancel their subscription(s):
a) Cancelling by MSISDN – via ‘STOP’ SMS; and
b) Cancelling by Account – via an inapp cancel button.
The APIs are further explained in the next sections.
a. 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 GlobalCharge to notify you of any subscriber cancellation requests via SMS.
Upon receiving a ‘STOP’ MO to a shortcode, GlobalCharge 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-urls?accountId=5557331&msisdn=447554090256&hs=GENERATED_HASH
Request Parameters:-
| PARAMETER | DESCRIPTION | EXAMPLE | |
|---|---|---|---|
| accountId | GlobalCharge provided unique Identifier for the client’s Android Application | accountId=5557331 | |
| msisdn | The mobile number of the end user. The number of the mobile being unsubscribedin 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=b0c148381420e72a 766e6289c846da3f |
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 unsubscription. | unsubscribeTicket= TK4532565679B | |
| numOfCancelledSubs | It 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 unsubscription response, GlobalCharge sends a confirmation SMS to the subscriber.
Review the diagram below for a more detailed flow of this API.
b. IN-APP Cancellation API
This API supports subscriber cancellations triggered from a Cancel button or similar within the APP itself. In this scenario, the cancelation request is sent from your APP 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 unsubscribe the user and lookup necessary data to pass through to GlobalCharge for unsubscription at our end. The parameters you will need to send in the request are defined below:
| PARAMETER | DESCRIPTION | EXAMPLE | |
|---|---|---|---|
| accountId | GlobalCharge 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=b0c148381420e72a 766e6289c846da3f |
Here’s an example request:
http://webapps.globalcharge.com:8040/inappservices_silent/rest/payments/unsubscribe_by_account?accountId=5557331&msisdn=447554090256&imsi=234549290401235&subscriptionTriggerId=243&unsubscribeTicket=TK4536562679&hs=GENERATED_HASH
GlobalCharge will then respond with a HTTP 200 Response of either “accepted” or “not_accepted” as described below:
| RESPONSE | DESCRIPTION | |
|---|---|---|
| Accepted | Unsubscription request has been accepted | |
| not_accepted | Unsubscription request has been rejected |
Following an “accepted” response, GlobalCharge will confirm the unsubscription with an SMS to the subscriber.
Review the diagram below for a more detailed flow of this API.
4. Subscription Reminders API
The Subscription Reminder 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:
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://webapps.globalcharge.com:8040/inappservices_silent/rest/payments/send_free_reminder_message?accountId=5557331&msisdn=447554090256&imsi=234549290401235&subscriptionTriggerId=243 &hs=GENERATED_HASH
GlobalCharge will then respond with a HTTP 200 Response of either “accepted” or “not_accepted” as defined in the In-App Cancellation API above.
| PARAMETER | DESCRIPTION | EXAMPLE |
|---|---|---|
| accountID | GlobalCharge 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 unsubscribedin 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 msisdn and the client’s Server-to-Server Hashing Salt (see the Connection Form) | hs=b0c148381420e72a766e6289c846da3f |
5. Subscription Status API
If you (the client) does not manage the subscription i.e. if subscription is managed by GlobalCharge, or Operator you may need to know the status of a subscription. Call this API to get the subscription status.
| PARAMETER | DESCRIPTION | EXAMPLE |
|---|---|---|
| accountID | GlobalCharge 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. URL Encode the msisdn using UTF-8 | 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 ID is the request ID (the OPT IN for subscription). All recurring billing requests must reference a valid subscriptionTriggerId. | subscriptionTriggerId=240 |
| hs | A 32 character security hash generated from the subscriptionTriggerId and the client’s Server-to-Server Hashing Salt (see the Connection Form). Md5( subscriptionTriggerId+salt) | reminderTicket= RG4532505629E |
Here’s an example request:
http://webapps.globalcharge.com:8040/inappservices_silent/rest/payments/check_sub_status?accountId=9923331&msisdn=%2331BA0F9AA78E30151C34F6010AE5D1A1&subscriptionTriggerId=6981332&imsi=208015403192359&hs=9f0d5cc436208bc9f1761e7920cb0972
GlobalCharge will then respond with a HTTP 200. Below table show possible return Responses:
| RESPONSE | DESCRIPTION |
|---|---|
| SUBSCRIBED | User is subscribed and will be rebilled if subscription is not cancelled |
| NOT_SUBSCRIBED | User is not subscribed |
REVISION HISTORY
| Version | Date | Description |
|---|---|---|
| 3.5 | 11-Jul-18 | Updated Documentaton |
| 3.4 | 21-Nov-16 | Updated Documentaton |
| 3.3 | 03-Feb-16 | Android Studio and Gradle Support |
| 3.2 | 07-Jan-14 | Support for operator managed subscription and Cancellation API |
| 3.1 | 04-Jun-13 | Support for WebView based operators billing |
| 3.0 | 05-May-12 | Subscription billing support |
| 2.4 | 07-Mar-11 | acknowledgePayment method added |
| 2.3 | 09-Feb-11 | paymentType parameter added |
| 2.2 | 26-Jan-11 | Updated androidManifest.xml and sample code |
| 2.1 | 12-Jan-11 | Sample code and confguration instructions added |
| 2.0 | 14-Dec-11 | New feature release |
| 1.1 | 05-Sep-10 | Updated for test app integration |
| 1.0 | 10-Aug-10 | First draft |