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

Integration Security

It is absolutely mandatory that the hash (or checksum) is computed again after you receive response from PayUMoney and compare it with request and post back parameters. This will protect you from any tampering by the user and help in ensuring a safe and secure transaction experience. It is mandate that you secure your integration with PayU by implementing Get Payment Response webservice and Webhook/callback as a secondary confirmation of transaction response. Detailed integration process of Get Payment Response webservice and Webhook and be found further in this document.

You need to ensure that sensitive information related to the integration is not part of the payment request to PayU. The details including — but not limited to — the following are considered sensitive information:

  • salt value
  • plain text hash string

Along with the request, the sensitive information should not be a part of any merchant-level URL. The following are considered sources for the merchant-level URL:

  • The last web address accessed by a browser before loading PayU’s checkout page.
  • URLs shared as part of payment request to PayU in the parameters: surl, furl, curl, nurl, and termUrl.
  • Notification URLs configured with the merchant account.
  • Invoice Completion URLs configured with the merchant account.

Note: PayUMoney will not be responsible for any security breaches (including any data breaches) that may occur due to non-implementation of the aforesaid security features at your end or any loss or damage arising therefrom, to you or to any third-party.

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);
};