Why PayGol?
How convenient and easy is your payment model from the user's point ofview? Is a credit card number or bank account information prerequisites 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 her 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 how the PayGol payment model works:
Figure 1
Making a payment using PayGol Android SDK consists of the following steps:
- 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.
- If the request has been accepted, PayGol server returns the accepted payment parameters to PayGol Android SDK. This step corresponds to arrow 2 in Figure 1.
- After a payment request is accepted by the PayGol server, PayGol Android SDK automatically executes the following three steps.
- The SDK programmatically communicates the payment parameters that PayGol server has accepted to the integrating software. This is part of step 3 in Figure 1.
- The SDK displays the payment parameters that PayGol server has accepted to the end user and asks if she accepts them. This is also part of step 3 in Figure 1.
- 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.
- PayGol server communicates with "Mobile Operators Network" to check if the payment is succeeded 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.
- After the SMS messages are sent by the PayGol SDK, as a final step, the integrating application should know whether the payment has been 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 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:
- Works asynchronously. The calls to its interface functions are non-blocking. Hence PayGol Android SDK is never going to cause a ANR error.
- 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. Hence 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:
Figure 2
Click 'Properties' to open the project properties. Next go to the 'JavaBuild Path' and the 'Libraries' tab.
Figure 3
Click 'Add External JARs' and browse to the location where PayGolSDK.jarfile is.
Add permissions in the AndroidManifest.xml
Thefollowing 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 internet connection is necessary for communicating with the PayGolserver for making payments.
The permission "android.permission.SEND_SMS" is required because the payment model is based on sending SMS messages.
PayGolAndroid 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 project settings and the permissions are added in the manifest file, you are ready to use PayGol AndroidSDK in the code. The steps below explain in detail every step which needs to be followed. Figure 4 displays the sequence diagram of the integration.
Figure 4
Step 1 – Instantiate
Instantiate an PayGolSDK object. There are two constructors to choose from:
PayGolSDK(Context context)
PayGolSDK(Context context,
PayGolSDKConfig config)Both constructors take the appllication context as parameter. The second constructor takes a configuration object also as parameter. For further information on configuration object and the default configuration parameters please refer to section 'PayGolSDKConfigObject'.
Step 2 – Configure (Optional)
PayGolSDK can be configured after the instantiation step also. In realityPayGolSDK 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 'PayGolSDKConfigObject'.
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 MakePaymentmethod 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 is necessary to have access to the currently displayed activity object. Hence the need for the parameter activity to the method <code>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
PayGolSDK 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 which state the payment is currently at. 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 the payment isat.
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. PayGolserver, 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 which stores the payment parameters PayGol server accepted. Please refer to section 'PayGolSDKProductObject' for further explanation of this object.
Similar to onAction, the parameter userArgs is the user arguments object which 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, 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 communicates a time-out code. The period and the maximum time IsPaymentSuccessful runs are part ofthe 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 – ImplementPayGolSDKListener.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 which stores a code showing if the payment has succeeded or not.
Finally, the parameter payment is a pointer to the PayGolSDKPayment objectfrom 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 configure the following options of PayGol SDK:
- 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. - 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)
- 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. - 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.
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 been 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 (possibly with adjusted price and currency).
Suggestions?
For suggestions and comments please contact:
Ali Chousein
P.S.
PayGol Android SDK got officially released. Related links:
http://www.paygol.com/android/implementation
http://www.paygol.com/newservice
