Mobile sms payments for any Android App using PayGol
Mobile Payments for Android AppsFast, secure, and easy payment method basedon SMS messages.No need to enter your banking information, offering ourfull coverage of countries, this is the only method youllever need for your Android applications! For Reference please visit our Android Section at: http://www.paygol.com/android/implementation
Mobile Payments for Android Apps 1 In-App Payment Request 2 Accept to confirm payment The possibilities are Endless! A Real fast and easy way to make your In-App payments. 3 Ready to Go!
Why PayGol? How convenient and easy is your payment model from the users point of view? 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 number 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, he/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 for 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 his/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:1. Make a payment request at the PayGol server. This step is initiated programmatically by the integrating application and itcorresponds to arrow 1 in Figure 1.2. If the request has been accepted, PayGol server returns the accepted payment parameters to PayGol Android SDK. Thisstep 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 threesteps: a. The SDK programmatically communicates the payment parameters that PayGol server has accepted to the integratingsoftware. This is part of step 3 in Figure 1. b. The SDK displays the payment parameters that PayGol server has accepted to the end user and asks if he/she acceptsthem. This is also part of step 3 in Figure 1. c. If the end user accepts the payment conditions, the SDK proceeds with sending the SMS message(s) to complete thepayment. This is shown as 4 in Figure 1.4. 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 anapplication.5. After the SMS messages are sent by the PayGol SDK, as a final step, the integrating application should know whether thepayment has been suceeded or not. For this purpose it makes a final call to the PayGol server. This step is initiatedprogrammatically by the integrating application and it corresponds to arrow 6 in Figure 1. PayGol server replies back with theinformation 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 AndroidApp.
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. 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 EclipseThe PayGol Android SDK JAR library file (e.g.PayGolSDK.jar) should be added as an external JAR to theJava Build Path (Figure 2) :
Configure PayGolAndroid SDK in EclipseClick Properties to openthe project properties. Nextgo to the JavaBuild Pathand the Libraries tab(Figure 3) :Click Add External JARs andbrowse to the location wherePayGolSDK.jarfile is.
Add permissions in the AndroidManifest.xmlThe 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 internet connection isnecessary for communicating with the PayGol server for making payments.The permission "android.permission.SEND_SMS" is required because the payment model isbased on sending SMS messages.PayGol Android SDK attaches the IMEI to the payment request for the transactions uniqueidentification and traceability.The permission "android.permission.READ_PHONE_STATE" is necessary for reading the IMEI of the phone.
Integrate PayGol Android SDKOnce PayGolSDK.jar is configured in project settings and the permissions are added in the manifest file, you are ready to use PayGolAndroid SDK in the code. The steps below explain in detail every step which needs to be followed. Figure 4 displays the sequencediagram of the integration
Step 1 – InstantiateInstantiate an PayGol SDK object. There are two constructors to choose from:PayGolSDK(Context context)PayGolSDK(Context context, PayGolSDKConfig config)Both constructors take the application context as parameter. The second constructor takes a configuration object also asparameter. For further information on configuration object and the default configuration parameters please refer tosection PayGolSDKConfigObject.Step 2 – Configure (Optional)PayGol SDK can be configured after the instantiation step also. In reality PayGol SDK can be reconfigured at any step.For this purpose you use the following method of PayGol SDK object:void SetPayGolSDKConfig(PayGolSDKConfig config)For further information on configuration object and the default configuration parameters please refer to sectionPayGolSDKConfigObject.
Step 3 – Make a payment requestWhen a payment should be done, its necessary to make a payment request at the PayGol server. For this purpose youshould call the MakePaymentmethod of PayGol SDK. There are four overloaded choices:void MakePayment(final PayGolSDKProduct product, final String language, final Activity activity, finalPayGolSDKListener.OnMakePaymentListener listener)void MakePayment(final PayGolSDKProduct product, final Stringlanguage, final Activity activity, final PayGolSDKListener.OnMakePaymentListener listener, final Object userArgs)voidMakePayment(final PayGolSDKProduct product, final String language, final Activity activity, final PayGolSDKListener.OnMakePaymentListener listener, final String custom)void MakePayment(final PayGolSDKProduct product, final Stringlanguage, final Activity activity, final PayGolSDKListener.OnMakePaymentListener listener, final String custom, finalObject userArgs)
PayGolSDKProduct object has three members: your service_id, the price and the currency of the requested payment. Please refer tosection 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. Thisparameter is necessary because PayGol SDK is going to display a dialog to the end user and ask whether he/she accepts the paymentconditions or not. The code for displaying this dialog is always running in the UiThread context so that a developer does not have tothink when to change the thread context. For running a piece of code in the UiThread context is necessary to have access to thecurrent 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 belowexplains 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 tostore 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 andonData methods of PayGolSDKListener.OnMakePaymentListener are invoked. This is very convenient when you want to augmentthe payment requests with more data to be displayed or processed when the payment has suceeded for example.
Step 3.1 – Implement PayGolSDKListener.OnMakePaymentListenerPayGol SDK defines PayGolSDKListener.OnMakePaymentListener, which is an interface you shouldimplement and pass its instance to MakePayment when making a payment request. The implementation shouldoverride three methods:voidvoid onAction(int which, Object userArgs)PayGol SDK invokes onAction to report which state the payment is currently at. Typical scenariosare: when the PayGol server rejects the payment, when the SMS messages cannot be sent ordelivered or when the SMS messages are sent and delivered. The documentation enumerates everycase 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 userarguments 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 hasaccepted the payment request. The payment parameters which you specify when making a payment request (pleasesee 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 thecountry where the end user is. When a payment has been accepted, onData programmatically communicates to yourapplication the payment parameters PayGol server has accepted.The parameter product is the object which stores the payment parameters PayGol server accepted. Please refer tosection 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 userarguments object has been passed to MakePayment, then userArgs stores null.void onResult(PayGolSDKPayment payment)When the SMS messages, necessary for making the payment, aresucessfully delivered, PayGol SDK invokes the onResult method. This method passes to your application aPayGolSDKPayment object (e.g. payment) which is necessary to later check whether the payment has beensucceeded or not.Step 4 – Check if the payment has succeededAfter 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 thepayment has actually succeeded or not at the PayGol server. For this purpose you use the IsPaymentSuccessfulmethod of PayGolSDKPayment which you got from onResult. IsPaymentSuccessful runs periodically for a specifiedperiod of time; if it detects that the payment has succeeded it communicates a success code to your application. If itcannot 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 communicatesthe result whether the payment has succeeded or not. More information is given in step 4.1.Step 4.1 – ImplementPayGolSDKListener.OnIsPaymentSuccessfulListenerIt is an interface you should implement and pass its instance to IsPaymentSuccessful. Theimplementation 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 theIsPaymentSuccessful method was called. This is convenient when you want to know for whichtransaction the onAction method is invoked.
PayGolSDKConfig ObjectPayGolSDKConfig enables a developer 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 ofPayGolSDK. 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 beendesigned and is very useful during the implementation phase when the developer needs to test the integration without having to pay forevery run of the payment cycle. Please contact PayGol support to verify which service id to use for the simulated mode. Thecorresponding 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 paymenthas 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 paymenthas 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 thedefault value is 0 (zero) seconds. As an example, instead of controlling if the payment has been succeeded or not at times 10, 20, 30... ifyou want to control at times 10, 25, 45... you should specify periodControlPayment=10 and changePeriodControlPayment=5.
PayGolSDKProduct ObjectPayGolSDKProduct 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 inthe listener method onData of PayGolSDKListener.OnMakePaymentListener after PayGol server accepts the payment requested(possibly with adjusted price and currency).Thats all !For reference visit our Android Section at http://www.paygol.com/android/implementation