PayUmoney Cordova Plugin

Introduction

The Cordova plugin for the PayUmoney SDK enables merchants to accept payments in their Android and iOS app through the native PayUmoney SDK. Once integrated, the plugin allows apps written on Cordova to access the functionality provided by the native SDK.

Features of the PayUmoney SDK

The PayUmoney Mobile SDK is a complete out of the box solution to enable payment acceptance in your Android or iOS mobile app. The SDK provides a swathe of features to not only make it easy to accept payments but also provide an easy to use, intuitive checkout experience.

Key benefits of the PayUmoney SDK are:

  • Accept payments through 100+ payment methods
  • Ready to use, native checkout experience to provide a secure and robust payment journey
  • User friendly features such as Saved Cards, Order Review, and OTP Assist

Prerequisites

  • Sign up with PayUmoney as merchant
  • Get the Merchant Id,Key and Salt, which are available on your merchant dashboard

Setting up the Cordova Plugin

To add the plugin to your Cordova development project, execute the following command from the console:

 $ cordova plugin add com.payumoney.sdkui.cordova

Integrating the SDK with your app

The PayUmoney Cordova plugin adds 2 JavaScript files to your project:

  1. `PayUMoneyPNPPlugin.js`: A wrapper around the native SDK. You can use the functions and classes defined in this script.
  2. `PayU-Helper.js`: A helper file which defines the `PUMTxnParam`, `PUMStyle` and `PUMEnvironment` classes for use with `PayUmoneyPnP`.

To integrate with the PayUmoney SDK, you will need to include the PayU-Helper.js file in your index.html located as `<app_name>/www/index.html`

In the index.html, add the following line after the statement importing the `cordova.js` file:

<script type="text/javascript" src="js/PayU-Helper.js"></script>

Ensure that the PayU-Helper.js file is located in the `js` folder in your project’s source directory.

Initializing the PayUmoney Cordova Plugin

Once the plugin files have been successfully included in your project, you need to instantiate the plugin. A sample code snippet illustrating the plugin initialization is provided below:

/**
* The showPaymentUI initializes the PayUmoney Cordova Plugin. You need to set the following parameters in the showPaymentUI menthod:
* merchantID: Your PayUmoney Merchant Id (mid)
* key: Your PayUmoney Merchant key
* txnId: A unique transaction ID to identify the transaction
* amount: Amount to be billed to the customer
* phoneNumber: Your customer’s mobile phone number(Will also be used to fetch the customer’s previously saved cards)
* email: Your customer’s email address (Will also be used to fetch the customer’s previously saved cards)
* userFirstName: Your customer’s first name
* environment_value: Environment. This should be one of PUMEnvironment.PUMEnvironmentTest or PUMEnvironment.PUMEnvironmentProduction. The test envionment must only be used when testing the integration. The value must be set to production before releasing your app
* sURL: Your Success URL where PayUmoney will notify of successful completion of transactions
* fURL: Your Failure URL where PayUmoney will notify of transaction failures if any
* product_description: Your Product description
* Udf1...udf10: User Defined Fields – You can pass custom information related to the transaction or product in these fields. They are optional so send empty strings if no data needs to be passed through these fields
**/

showPaymentUI: function(payment) {
   var merchantID = '<Your_Merchant_ID>';
   var key = '<Your_Merchant_Key>';
   var txnId = '<Unique_Transaction_ID>';
   var amount = '123.45'; // Amount in INR
   var phoneNumber = '1234567890'; // Provide a valid phone number of the user to fetch saved cards
   var email = 'abc@de.com'; // Provide valid email of user to fetch saved cards
   var userFirstName = 'UserFirstName ';
   var environment_value = PUMEnvironment.PUMEnvironmentTest; // select your Environment Set to PUMEnvironment.PUMEnvironmentProduction before app release
   var sURL = '<Your_Success_URL>'; //PayUmoney will give a call back to this URL on successful transactions
   var fURL = '<Your_Failure_URL>'; //PayUmoney will give a call back to this URL on failed transactions
   var product_description = '<Your_Product_description>'; // Short description of your product
   var udf1 = ''; //User Defined Fields – Free form field to include additional information about the transaction
   var udf2 = '';
   var udf3 = '';
   var udf4 = '';
   var udf5 = '';
   var udf6 = '';
   var udf7 = '';
   var udf8 = '';
   var udf9 = '';
   var udf10 = '';
// Create a PUMTxnParam object passing it the parameters declared above. The UDF parameters are optional User Defined Fields
        var txnParam = new PUMTxnParam(key, merchantID, txnId, amount, phoneNumber, email, userFirstName, sURL, fURL, product_description, environment_value, udf1, udf2, udf3, udf4, udf5, udf6, udf7, udf8, udf9, udf10);

    /**
        For ensuring transaction security, you need to generate a hash on your server side and pass the hash to the PayUmoney backend.
        For more information on the hash generation, please see the section #Hash Generation at the end of this document
    */

txnParam.hashValue = '<Hash_Value_For_Current_Transaction>';
    /**
        Next call the plugin’s method showPaymentView and pass txnParam object to this method.
        The showPaymentView method will display the checkout screen.
        The method gives a success callback if the txnParam is created correctly, else it gives a failure callback.
    */
        cordova.plugins.PayUmoneyPnP.showPaymentView(txnSuccessHandler, txnFailureHandler, txnParam );

}

var txnSuccessHandler: function (response) {
        console.log('showPaymentView received Success');
        alert(JSON.stringify(response));
};

var txnFailureHandler: function (response) {
        console.log('showPaymentView received Failure');
        alert(JSON.stringify(response));
};

Customizing the Checkout Experience

The PayUmoney SDK provides a variety of customization options. To customize the look and feel of the PayUmoney SDK UI, use the methods described below:

Order Review

The Order Review feature allows displaying of the order details to your customers. This view is accessible to customers throughout the payment journey and is useful if your customers want to verify the order contents. The order details are fully customization and are not validated in any form. We will display the data as passed by the app.

To enable the Order Review display, call the setOrderDetails method on the Cordova plugin and pass the relevant order details you’d like to display to your customers. This method must be called before the showPaymentViewmethod is called

/**
      The setOrderDetails method accepts an object of JSON objects (Key-Value pairs) that are used to display the order details. The methods gives a callback based on the success or failure of the set order details method call.
**/

var setOrderDetails: function () {
         var orderDetails = [
                  {"From":"Delhi"},
                  {"To":"Pune"},
                  {"Date":"18-02-2018"},
                  {"Time":"08:45"},
                  {"Total":"4123.45"}
         ];

         cordova.plugins.PayUmoneyPnP.orderDetails(orderDetailsSuccessHandler, orderDetailsFailureHandler, orderDetails);
}

var orderDetailsSuccessHandler: function (response) {
         console.log(‘Order details set successfully');
};

var orderDetailsFailureHandler: function (response) {
         console.log('Order details received Failure with an error response : '+ response);
};

Setting the checkout theme

The plugin also provides the ability to set a color theme for the entire payment experience. This allows the checkout UI’s look and feel to match the native app’s look and feel. This theme can be set for both Android and iOS devices. While the PayUmoney SDK is shipped with pre-defined schemes, apps can also define their own custom color scheme.

To set a custom color scheme, include the following code snippets in your app:

Setting the Android Theme:

/**
* The theme needs to be defined in the app’s styles.xml and must include a name for the theme.
* You only need to pass the theme name to the setAndroidAppThemeName method and the SDK 
* takes care of the rest. On successfully setting the theme, the method will give a call back to
* the success handler method else will give a callback to the failure handler method.
*/

var setAndroidAppThemeName: function() {
         var themeName = '<#Your_Theme_Name#>'; // e.g. 'AppTheme.Green’. Define this theme in your styles.xml as shown. If invalid, the Plugin will select a default theme.
        cordova.plugins.PayUmoneyPnP.setAndroidAppThemeName( orderDetailsSuccessHandler, orderDetailsFailureHandler, themeName);
};

var andThemeSuccessHandler: function (response) {
        console.log('payButtonClicked(): setAndroidAppThemeName received Success');
};

var andThemeFailureHandler: function (response) {
        console.log('payButtonClicked(): setAndroidAppThemeName received Failure :: ' + response);
};

Sample of styles.xml

<stylename="AppTheme.Green"parent="PayumoneyAppTheme">
        <itemname="colorPrimary">@color/persian_green_primary</item> // Define these colors in colors.xml
        <itemname="colorPrimaryDark">@color/persian_green_dark</item>
        <itemname="colorAccent">@color/persian_green_accent</item>
        <itemname="colorButtonNormal">@color/persian_green_primary</item>
        <itemname="alertDialogTheme">@style/AlertDialogStyle_green</item>
        <itemname="actionMenuTextColor">@color/white</item>
</style>

<stylename="AppTheme.pink"parent="PayumoneyAppTheme">
       <itemname="colorPrimary">@color/pink_primary</item>
       <itemname="colorPrimaryDark">@color/pink_dark</item>
       <itemname="colorAccent">@color/pink_accent</item>
       <itemname="colorButtonNormal">@color/pink_primary</item>
       <itemname="alertDialogTheme">@style/AlertDialogStyle_pink</item>
       <itemname="actionMenuTextColor">@color/white</item>
</style>

Setting the iOS Theme:

/**
* For iOS App, you need to define the color scheme as hex values and pass it to the theming method
* On successfully setting the theme, the method will give a call back to the 
* success handler method else will give a callback to the failure handler method.
*/

var setiOSAppTheme: function() {
        var topBarColor = '0A927A';
        var topTitleTextColor = 'ffffff';
        var buttonColor = '0A927A';
        var buttonTextColor = 'ffffff';
        cordova.plugins.PayUmoneyPnP.setiOSAppTheme( iOSThemeSuccessHandler, iOSThemeFailureHandler, topBarColor, topTitleTextColor, buttonColor, buttonTextColor);
}

var iOSThemeSuccessHandler: function (response) {
        console.log('payButtonClicked(): setiOSAppThemeName received Success');
};

var iOSThemeFailureHandler: function (response) {
        console.log('payButtonClicked(): setiOSAppThemeName received Failure :: ' + response);
};