Table of Contents

• Overview
• Merchant Onboarding
• Installation
• Configuration
• Initialization
• Checkout Request
• Checkout
• Checkout Button
• Transaction Result
  • Intent Scheme

Overview

This Cordova plugin enables to use commerce-web SDK in a Cordova project. commerce-web is a lightweight library used to integrate Merchants with EMV Secure Remote Commerce and Mastercard's web-based SRC-Initiator. commerce-web facilitates the initiation of the checkout experience and returns the transaction result to the Merchant after completion.

The cordova plugin provides a wrapper around our App2Web SDKS - commerce-web-android for Android and MCSCommerceWeb for iOS Mobile platform. We recommend Merchants to use our Cordova plugin only on Hybrid Mobile applications built using Apache Cordova framework. If you are building a full native application, we recommend directly integrating to our App2Web SDKs.

More information on App2Web SDKs can be found on the links below:

Link to commerce-web-android: https://github.com/Mastercard/commerce-web-android

Link to MCSCommerceWeb for iOS: https://github.com/Mastercard/MCSCommerceWeb

Onboarding

Merchants looking to integrate our cordova plugin must complete the onboarding steps on Mastercard Developer Portal.

Steps for Merchant Onboarding:

1. Create an account on Mastercard Developer Portal and follow the steps to create New "Click to Pay API" project.
2. Once the project is setup, Merchant will be taken to the Project's dashboard. This page will help configure checkoutId for Sandbox/Prod environments along with callbackUrl etc.

It is very important to configure these values properly on the portal. If these values are not configured in proper format, merchant application will not be able to do successful checkout.

Android:

callbackUrl must be configured with an Intent URI. Below is an example format of callbackUrl for a sample merchant application named FancyShop

• Example format of callbackUrl: intent://{$host}}/#Intent;scheme={$scheme};package={$package_name};end
• Channel: Android

iOS:

callbackUrl must be configured as URL Schemes. Below is an example format of callbackUrl for a sample iOS merchant application named FancyShop

Example format of callbackUrl: fancyshop:// Channel: IOS

3. The above steps completes onboarding procedure and now the Merchant App can begin cordova plugin installation.

Installation

To include app-to-web plugin in Cordova Merchant application, run following command

$ cordova plugin add mastercard-cordova-commerceweb

Configuration

To initialize SDK, a configuration object needs to be provided. Configuration object requires the following parameters:

• checkoutId: The unique identifier assigned to the merchant during onboarding.
• checkoutUrl: The URL used to load the checkout experience. Note: when testing in the Sandbox environment, use https://sandbox.src.mastercard.com/srci/. For Production, use https://src.mastercard.com/srci/.
• locale: This is the locale in which the transaction is processing.
• allowedCardTypes: The payment networks supported by this merchant (e.g. master, visa, amex)
• callbackScheme: This must match the scheme component of the callbackUrl configured for this merchant. This value is required to redirect back to the merchant from the plugin. (IOS only)

Configuration object can be created as shown below:

/**
 SDK Configuration Model Android
*/
var configurationAndroid = {
     "checkoutId": "{YOUR-CHECKOUT-ID}",
     "checkoutUrl": "https://sandbox.src.mastercard.com/srci/",
     "locale": "en_US",
     "allowedCardTypes": [
          "master",
          "visa",
          "amex"
         ]
}

/**
 SDK Configuration Model IOS
*/
var configurationIOS = {
     "checkoutId": "{YOUR-CHECKOUT-ID}",
     "checkoutUrl": "https://sandbox.src.mastercard.com/srci/",
     "locale":"en_US",
     "callbackScheme":"{YOUR-SCHEME}",
     "allowedCardTypes": [
          "master",
          "visa",
          "amex"
         ]
}

Initialization

Before you can perform a checkout you need to initialize the SDK by calling initializeSdk method, can be called as shown below:

 /**
 Initialization SDK call
*/
function initializeMethod() {
     cordova.plugins.mastercard.CordovaCommerceWeb.initializeSdk(configuration);
}

Checkout Request

checkoutRequest: Data object with transaction-specific parameters needed to complete checkout. This request can also override existing merchant configurations.

Here are the required and optional fields:

Parameter	Type	Required	Description
amount	Double	Yes	The transaction total to be authorized
cartId	String	Yes	Randomly generated UUID used as a transaction id
currency	String	Yes	Currency of the transaction
callbackUrl	String	No	URL used to communicate back to the merchant application
cryptoOptions	Set<CryptoOptions>	No	Cryptogram formats accepted by this merchant
cvc2Support	Boolean	No	Enable or disable support for CVC2 card security
shippingLocationProfile	String	No	Shipping locations available for this merchant
suppress3Ds	Boolean	No	Enable or disable 3DS verification
suppressShippingAddress	Boolean	No	Enable or disable shipping options. Typically for digital goods or services, this will be set to true
unpredictableNumber	String	No	For tokenized transactions, unpredictableNumber is required for cryptogram generation
validityPeriodMinutes	Integer	No	The expiration time of a generated cryptogram, in minutes

Checkout Request Model Examples

/**
  Checkout Request Model Android
 */
 var checkoutRequestAndroid = {
      "amount": 3.14,
      "currency": "USD",
      "cartId": create_UUID(),
      "suppressShippingAddress": "false",
      "cryptoOptions": [
            "ICC",
            "UCAF"
           ]
 }
 
 /**
  Checkout Request Model IOS
 */
 var checkoutRequestIOS = {
      "amount": 3.14,
      "currency": "USD",
      "cartId": create_UUID(),
      "callbackUrl":"fancyshop:// | {YOUR-SCHEME}",
      "suppressShippingAddress": "false",
      "cryptoOptions": [
            "ICC",
            "UCAF"
           ]
 }

/**
  Create UUID
 */
 function create_UUID(){
     var dt = new Date().getTime();
     var uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
         var r = (dt + Math.random()*16)%16 | 0;
         dt = Math.floor(dt/16);
         return (c=='x' ? r :(r&0x3|0x8)).toString(16);
     });
     return uuid;
 }

Checkout

After SDK initialization you can call checkout with a CheckoutRequest model, plugin will return Transaction ID as a String inside the callback transactionId

/**
  Checkout SDK call
 */
 function checkoutMethod() {
      var devicePlatform = device.platform;
      if(devicePlatform === "iOS"){
          cordova.plugins.mastercard.CordovaCommerceWeb.checkout(checkoutRequestIOS,
           function(transactionId, error){
                if(error){
                     document.getElementById("checkoutResponse").value="Checkout SDK Failed!";
                }else{
                     //display transaction id
                     document.getElementById("checkoutResponse").value=transactionId;
                }
           });
      }else if(devicePlatform === "Android"){
          cordova.plugins.mastercard.CordovaCommerceWeb.checkout(checkoutRequestAndroid,
           function(transactionId, error){
                if(error){
                     document.getElementById("checkoutResponse").value="Checkout SDK Failed!";
                }else{
                     //display transaction id
                     document.getElementById("checkoutResponse").value=transactionId;
                }
          });
      }
  }

Checkout Button

Merchant can obtain our checkout button image calling the getCheckoutButton by passing a checkoutRequest model and listening for the callback getCheckoutButtonSuccess

 cordova.plugins.mastercard.CordovaCommerceWeb.getCheckoutButton(checkoutRequest, getCheckoutButtonSuccess);

We return a Base64 encoded image to the merchant, it can be resize and display base on merchant needs

//html image tag with style class
 <img id="checkoutButton" class="srcButton"></img>

//CSS to display image
.srcButton{
    background-size: 100%;
    background-position: top center;
    background-repeat:no-repeat;
    width:235px;
    height:55px;
    border:none;
}

/**
 Get Checkout Button Image call
*/
function getCheckoutButtonMethod() {
     var getCheckoutButtonSuccess = function(checkoutButtonImage) {
     //display image button to element on html
     document.getElementById("checkoutButton").src = checkoutButtonImage;
     }
     cordova.plugins.mastercard.CordovaCommerceWeb.getCheckoutButton(checkoutRequest, getCheckoutButtonSuccess);
     }
}

Android Specific

Transaction Result

The result of a transaction is returned to the application via an Intent containing the transactionId.

Intent Scheme

callbackUrl must be configured with an Intent URI. The transaction result is returned to the activity configured to receive the Intent. would define a URI similar to

intent://{YOUR-HOST}/#Intent;package={YOUR-PACKAGE};scheme={YOUR-SCHEME};end

In order to receive the result, the application must declare an intent-filter for the Activity receiving the Intent, the plugin already adds for you the intent filter, you only need to replace your scheme in the application AndroidManifest.xml

<data
                    android:host="commerce"
                    android:path="/"
                    android:scheme="{YOUR SCHEME}"/>