mastercard-cordova-commerceweb

    1.0.1 • Public • Published

    Table of Contents

    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

    1. 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}"/>

    Install

    npm i mastercard-cordova-commerceweb

    DownloadsWeekly Downloads

    2

    Version

    1.0.1

    License

    Apache-2.0

    Unpacked Size

    51.9 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar