PayGol Android SDK – Payment Model using SMS

Why PayGol?

How convenient and easy is your payment model from the user’s point of view? Is a credit card number or bank account information a prerequisite for buying a service in your payment model? Do users have doubts about security when they provide their credit card numbers or bank account information? Is it possible to have a different, yet more practical payment model, which does not require providing any data? Luckily the answer is yes. PayGol provides you a payment model using SMS messages. When a user buys a service, she makes the payment by sending only SMS messages and she does not provide any personal data. PayGol technology is practical, secure, easy to integrate and convenient both for developers who integrate a payment model and for end users who buy a service.

Overview

In this article we introduce the PayGol Android SDK and explain in detail how a developer can integrate it in an Android application. PayGol Android SDK is a JAR library for Android based mobile phones and is used for making payments using SMS messages. The figure below shows an overview of how the PayGol payment model works:

The 'Java Build Path' and the 'Libraries' tab
Figure 1: Overview of how the PayGol payment model works

Making a payment using PayGol Android SDK consists of the following steps:


  1. Make a payment request at the PayGol server. This step is initiated programmatically by the integrating application and it corresponds to arrow 1 in Figure 1.
  2. If the request has been accepted, the PayGol server returns the accepted payment parameters to PayGol Android SDK. This step corresponds to arrow 2 in Figure 1.
  3. After a payment request is accepted by the PayGol server, PayGol Android SDK automatically executes the following three steps.

    1. The SDK programmatically communicates the payment parameters that the PayGol server has accepted to the integrating software. This is part of step 3 in Figure 1.
    2. The SDK displays the payment parameters that the PayGol server has accepted to the end user and asks if she accepts them. This is also part of step 3 in Figure 1.
    3. If the end user accepts the payment conditions, the SDK proceeds with sending the SMS message(s) to complete the payment. This is shown as 4 in Figure 1.

  4. PayGol server communicates with “Mobile Operators Network” to check if the payment has suceeded or not. This is 5 in Figure 1. This step is executed by the server and is not part of integrating the PayGol Android SDK in an application.
  5. After the SMS messages are sent by the PayGol SDK, as a final step, the integrating application should know whether the payment has suceeded or not. For this purpose it makes a final call to the PayGol server. This step is initiated programmatically by the integrating application and it corresponds to arrow 6 in Figure 1. PayGol server replies back with the information, which it got from “Mobile Operators Network”. This is shown as step 7 in Figure 1.

The section below explains all the necessary steps in detail for configuring and integrating PayGol Android SDK in any Android application.

How to Use PayGol Android SDK?

The PayGol Android SDK:


  1. Works asynchronously. The calls to its interface functions are non-blocking. Hence PayGol Android SDK is never going to cause a ANR error.
  2. Always works in the right thread context. Whenever it needs to display a popup, it executes the corresponding statements in the UI thread context; otherwise it executes statements in background threads. A developer does not have to think whether she should switch thread contexts when making calls to PayGol SDK interface methods.

The explanation in this section assumes that the IDE used is Eclipse.

Configure PayGol Android SDK in Eclipse

The PayGol Android SDK JAR library file (e.g. PayGolSDK.jar) should be added as an external JAR to the Java Build Path:

Overview of how the PayGol payment model works
Figure 2: The PayGol Android SDK JAR library file should be added as an external JAR

Click ‘Properties’ to open the project properties. Next go to the ‘Java Build Path’ and the ‘Libraries’ tab.

The PayGol Android SDK JAR library file should be added as an external JAR
Figure 3: The ‘Java Build Path’ and the ‘Libraries’ tab

Click ‘Add External JARs’ and browse to the location where PayGolSDK.jar file is.

Add Permissions in the AndroidManifest.xml

The following three permissions should be added in AndroidManifest.xml:

uses-permission android_name="android.permission.INTERNET"
uses-permission android_name="android.permission.SEND_SMS"
uses-permission android_name="android.permission.READ_PHONE_STATE"

The permission “android.permission.INTERNET” is needed because an internet connection is necessary for communicating with the PayGol server for making payments.

The permission “android.permission.SEND_SMS” is required because the payment model is based on sending SMS messages.

PayGol Android SDK attaches the IMEI to the payment request for the transactions’ unique identification and traceability. The permission “android.permission.READ_PHONE_STATE” is necessary for reading the IMEI of the phone.

Integrate PayGol Android SDK

Once PayGolSDK.jar is configured in the project settings and the permissions are added in the manifest file, you are ready to use PayGol Android SDK in the code. The steps below explain in detail every step that needs to be followed. Figure 4 displays the sequence diagram of the integration.

The sequence diagram of the integration
Figure 4: The sequence diagram of the integration

Step 1 – Instantiate:

Instantiate a PayGolSDK object. There are two constructors to choose from:

PayGolSDK(Context context)
PayGolSDK(Context context,
          PayGolSDKConfig config)

Both constructors take the application context as a parameter. The second constructor also takes a configuration object as a parameter. For further information on configuration object and the default configuration parameters please refer to section ‘PayGolSDKConfig Object’.

Step 2 – Configure (Optional):

PayGol SDK can be configured after the instantiation step. In reality PayGolSDK can be reconfigured at any step. For this purpose you use the following method of PayGolSDK object:

void SetPayGolSDKConfig(PayGolSDKConfig config)

For further information on configuration object and the default configuration parameters please refer to section ‘PayGolSDKConfig Object’.

Step 3 – Make a payment request:

When a payment should be done, it’s necessary to make a payment request at the PayGol server. For this purpose you should call the MakePayment method of PayGolSDK. There are four overloaded choices.

void MakePayment(final PayGolSDKProduct product,
                 final String language,
                 final Activity activity,
                 final PayGolSDKListener.OnMakePaymentListener listener)

void MakePayment(final PayGolSDKProduct product,
                 final String language,
                 final Activity activity,
                 final PayGolSDKListener.OnMakePaymentListener listener,
                 final Object userArgs)

void MakePayment(final PayGolSDKProduct product,
                 final String language,
                 final Activity activity,
                 final PayGolSDKListener.OnMakePaymentListener listener,
                 final String custom)

void MakePayment(final PayGolSDKProduct product,
                 final String language,
                 final Activity activity,
                 final PayGolSDKListener.OnMakePaymentListener listener,
                 final String custom,
                 final Object userArgs)

PayGolSDKProduct object has three members: your service_id, the price, and the currency of the requested payment. Please refer to section ‘PayGolSDKProduct Object’.

The parameter language can have one of the four values: en, de, fr, es, and it specifies the language to be used during the payment (e.g. the language of the messages displayed to the end user).

The next parameter activity is the current visible activity of your Android application, while the payment is in progress. This parameter is necessary because PayGol SDK is going to display a dialog to the end user and ask whether she accepts the payment conditions or not. The code for displaying this dialog is always run in the UiThread context so that a developer does not have to think when to change the thread context. For running a piece of code in the UiThread context, it is necessary to have access to the currently displayed activity object. Hence the need for the parameter activity to the method PayGolSDK.MakePayment.

PayGolSDKListener.OnMakePaymentListener is a listener object communicating the result of the payment request. Step 3.1 below explains PayGolSDKListener.OnMakePaymentListener more in detail.

The optional parameter custom is.a placeholder field, which can be used for miscellaneous purposes. One of its typical use cases is to store the unique identifier of the end user. This unique identifier can be the user id or the session id in an online game environment, so that the PayGol server will know which exact user is buying a service.

Finally the optional parameter userArgs is any object you pass to MakePayment and later you get back when the onAction and onData methods of PayGolSDKListener.OnMakePaymentListener are invoked. This is very convenient when you want to augment the payment requests with more data to be displayed or processed when the payment has suceeded for example.

Step 3.1 – Implement PayGolSDKListener.OnMakePaymentListener:

PayGol SDK defines PayGolSDKListener.OnMakePaymentListener, which is an interface you should implement and pass its instance to MakePayment when making a payment request. The implementation should override three methods:

void onAction(int which,
              Object userArgs)

PayGolSDK invokes onAction to report the current state of the payment. Typical scenarios are: when the PayGol server rejects the payment, when the SMS messages cannot be sent or delivered, or when the SMS messages are sent and delivered. The documentation enumerates every case when onAction is called.

The parameter which stores a code showing the latest state of the payment.

The parameter userArgs is the user arguments object, which you passed to MakePayment. If no user arguments object has been passed to MakePayment, then userArgs stores null.

void onData(PayGolSDKProduct product,
            Object userArgs)

The method onData is called when the PayGol server has accepted the payment request. The payment parameters, which you specify when making a payment request (please see section ‘PayGolSDKProduct Object’) are not necessarily the accepted ones by the PayGol server. PayGol server, when necessary, adjusts the specified price and currency based on the cost of sending an SMS message in the country where the end user is. When a payment has been accepted, onData programmatically communicates to your application the payment parameters PayGol server has accepted.

The parameter product is the object that stores the payment parameters PayGol server accepted. Please refer to section ‘PayGolSDKProduct Object’ for further explanation of this object.

Similar to onAction, the parameter userArgs is the user arguments object that you pass to MakePayment. If no user arguments object has been passed to MakePayment, then userArgs stores null.

void onResult(PayGolSDKPayment payment)

When the SMS messages, necessary for making the payment, are sucessfully delivered, PayGol SDK invokes the onResult method. This method passes to your application a PayGolSDKPayment object (e.g. payment), which is necessary to later check whether the payment has been succeeded or not.

Step 4 – Check if the payment has succeeded:

After the SMS messages have been delivered successfully and the onResult method of PayGolSDKListener.OnMakePaymentListener has been called, and before considering the transaction to be sucessful you should check if the payment has actually succeeded or not at the PayGol server. For this purpose you use the IsPaymentSuccessful method of PayGolSDKPayment, which you got from onResult. IsPaymentSuccessful runs periodically for a specified period of time; if it detects that the payment has succeeded it communicates a success code to your application. If it cannot detect that the payment has succeeded before the specified period of time, it comminucates a time-out code. The period and the maximum time IsPaymentSuccessful runs are part of the configuration parameters of PayGolSDK; for further information please refer to section ‘PayGolSDKConfig Object’.

void IsPaymentSuccessful(PayGolSDKListener.OnIsPaymentSuccessfulListener listener)

PayGolSDKListener.OnIsPaymentSuccessfulListener is a listener object, which communicates the result whether the payment has succeeded or not. More information is given in step 4.1.

Step 4.1 – Implement PayGolSDKListener.OnIsPaymentSuccessfulListener:

It is an interface you should implement and pass its instance to IsPaymentSuccessful. The implementation should override one method:

void onAction(int which,
              PayGolSDKPayment payment)

The parameter that stores a code showing if the payment has succeeded or not.

The parameter payment is a pointer to the PayGolSDKPayment object from which the IsPaymentSuccessful method was called. This is convenient when you want to know for which transaction the onAction method is invoked.

PayGolSDKConfig Object

PayGolSDKConfig enables a developer to configure the following options of PayGol SDK:


  1. If PayGol SDK is going to generate log information or not. This is necessary and very useful when debugging the integration of PayGolSDK. The corresponding member is PayGolSDKConfig.enableDebug and the default value is false.
  2. If the transactions will be done in real or simulalated mode. The real mode is when SMS messages are sent to make a payment. Simulated mode is when sending of SMS messages is simulated between PayGol SDK and PayGol server. The simulated mode has been designed and is very useful during the implementation phase when the developer needs to test the integration without having to pay for every run of the payment cycle. Please contact PayGol to verify which service id to use for the simulated mode. The corresponding member is PayGolSDKConfig.isSimulation and the default value is false.

    (The rest of the configuration parameters affect the execution of PayGolSDKPayment.IsPaymentSuccessful)

  3. The maximum time, in terms of seconds, PayGolSDKPayment.IsPaymentSuccessful executes to check if its corresponding payment has succeeded or not. The corresponding member is PayGolSDKConfig.maxTimeControlPayment and the default value is 60 (sixty) seconds.
  4. The base period, in terms of seconds, when PayGolSDKPayment.IsPaymentSuccessful executes to check if its corresponding payment has succeeded or not. The corresponding member is PayGolSDKConfig.periodControlPayment and the default value is 10 (ten) seconds.
  5. The constant variance of the base period. The corresponding member is PayGolSDKConfig.changePeriodControlPayment and the default value is 0 (zero) seconds. As an example, instead of controlling if the payment has succeeded or not at times 10, 20, 30… if you want to control at times 10, 25, 45… you should specify periodControlPayment=10 and changePeriodControlPayment=5.

PayGolSDKProduct Object

PayGolSDKProduct encapsulates three fields necessary for defining a product during a transaction at PayGol. These fields are service_id, price and currency. PayGolSDKProduct is passed as a parameter to MakePayment when making a payment request at PayGol server and retrieved in the listener method onData of PayGolSDKListener.OnMakePaymentListener after PayGol server accepts the payment requested (posisbly with adjusted price and currency).

Suggestions?

For suggestions and comments please contact:

Ali Chousein: [email protected]

More by Author

Must Read