# Masterpass Merchant Cordova SDK Plug-In for iOS and Android
source: https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/mobile-integration/masterpass-merchant-cordova-sdk-plug-in-for-ios-and-android/index.md

## Overview {#overview}

If you are a merchant who has a mobile application built using the Cordova or Phonegap frameworks, the Masterpass Merchant SDK Cordova Plugin allows you to add support for Masterpass merchant checkout without needing to build a native app or use Mastercard's native Android or iOS SDKs. If you are intending to build native Android or iOS apps, then see:  

* [Masterpass Merchant Android SDK](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/mobile-integration/masterpass-checkout-android-sdk-v28/index.md)
* [Masterpass Merchant iOS SDK](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/mobile-integration/masterpass-checkout-ios-sdk-v28/index.md)

### Pre-requisites {#pre-requisites}

The following table lists the minimum version of Cordova, Android and iOS which relate to the Masterpass Merchant SDK Cordova Plugin:

| Plugin version | Min Cordova CLI | Min Cordova Android | Max Cordova Android | Min Android API level | Min Cordova iOS | Min iOS version |
|----------------|-----------------|---------------------|---------------------|-----------------------|-----------------|-----------------|
| 1.1.0          | 8.1.2           | 7.1.2               | 7.1.2               | 19                    | 4.5.5           | 10.0            |

Note that the Masterpass Cordova plugin will not work with a version of Cordova for Android later than 7.1.2.

## Plugin download {#plugin-download}

The plugin is available for download from here:

|                                                                                  Zip file                                                                                   |                                       Contents                                       |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| [MerchantSDKPlugin_Sandbox_2.8.1.zip](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/uploads/merchantsdkplugin-sandbox-2.8.1.zip)       | Cordova / Phonegap plugin for Masterpass iOS and Android 2.8 release, for Sandbox    |
| [MerchantSDKPlugin_Production_2.8.1.zip](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/uploads/merchantsdkplugin-production-2.8.1.zip) | Cordova / Phonegap plugin for Masterpass iOS and Android 2.8 release, for Production |

Note that both downloads include code to support both iOS and Android.

## Installation {#installation}

The following instructions assume that you have already installed the Cordova or Phonegap CLI and placed the Mastercard plugin in an appropriate place.

To install from the Cordova or Phonegap command, use one of the following commands as appropriate:

**To install from the command line:**   
> cordova plugin add \[path_to_plugin\]

**To install from the command line:**   
> phonegap plugin add \[path_to_plugin\]

### Additional notes for iOS {#additional-notes-for-ios}

If you are building for iOS you will need to handle custom URL schemes as described below.

#### Handling Custom URL Schemes {#handling-custom-url-schemes}

To handle a custom URL scheme, implement the **application:OpenURL:annotation** in your App delegate. In this method, pass the **NSURL** object parameter to the **handleCheckoutFromMerchant()** method. This will handle the custom URL scheme callback based on the URL provided. This checks the validity of the returned URL as it will return false if URL callback is not correct for Masterpass merchant SDK.

Make sure your **AppDelegate** class imports **MerchantSDKPlugin.h**:
> #Import "MerchantSDKPlugin.h"

Add the following line in your **AppDelegate** class:
> static NSString \*const PLUGIN_NAME = @"MerchantSDKPlugin";

Now add the following code in your **AppDelegate** class:
* ObjectiveC

```ObjectiveC
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
	MerchantSDKPlugin *plugin = [self.viewController getCommandInstance:PLUGIN_NAME];
		if(plugin == nil) {
			NSLog(@"Unable to get instance of command plugin"); return NO;
		}
		BOOL handled = [plugin handleCheckoutFromMerchant:url];
		if(!handled) {
		}
	return handled;
}
```

## API Function Reference {#api-function-reference}

The following functions are provided by the plugin:  

1. Initialize Merchant SDK
2. Set User Details
3. Get Masterpass Button
4. Pairing With Express Checkout
5. Set User Details
6. Add Payment Method
7. Pairing Only For Express Checkout

To use each of these functions, you will first need to obtain an object representing the plugin, then you will be able to call the functions within that object.

The functions and the details to be passed are described below along with simple code examples.
Note: For the request object, make sure to send it as String for Android, and as regular JS Object for iOS.

### Initialize Merchant SDK {#initialize-merchant-sdk}

The **initialiseSDK** function initializes the merchant plugin on the native side. You must call this function each time your application starts, in order to use the functionality.
Note: You must wait until you receive the [deviceready](http://cordova.apache.org/docs/en/7.x/cordova/events/events.html#deviceready) event before calling this function (see the [Cordova documentation](http://cordova.apache.org/docs/en/latest/) for details of [event handling in Cordova](http://cordova.apache.org/docs/en/7.x/cordova/events/events.html).

#### Parameters {#parameters}

|    Parameter    |   Type   |                               Description                                |
|-----------------|----------|--------------------------------------------------------------------------|
| configuration   | Object   | An object describing relevant specific options for all target platforms. |
| successCallback | Function | Called if the SDK initializes successfully.                              |
| errorCallBack   | Function | Called if the SDK fails to initialize                                    |

The attributes of the **configuration** object are described below (the object is the same for both iOS and Android):

|       Parameter        |  Type   |                                         Description                                         |
|------------------------|---------|---------------------------------------------------------------------------------------------|
| locale                 | String  | The locale of current application (for example, "en_US").                                   |
| merchantName           | String  | The merchant name used while registering the merchant application on the Masterpass portal. |
| expressCheckoutEnabled | Boolean | Boolean flag specifying whether the app is enabled for express checkout.                    |
| checkoutId             | String  | Merchant checkout identifier received when merchant onboarded for Masterpass.               |

##### Callback parameters {#callback-parameters}

* successCallback - This function will not have any parameters.
* errorCallback - The parameter for this function is an object of type error (see below).

**errors**

|   Parameter   |  Type   |               Description                |
|---------------|---------|------------------------------------------|
| error.code    | Integer | Error code.                              |
| error.message | String  | Message describing the cause of failure. |

Example
* JavaScript

```JavaScript
var merchantSDKPlugin = cordova.require("cordova_Plugin_MerchantSDKPlugin.MerchantSDKPlugin");

var success = function() {
}

var failure = function(error) {
}

merchantSDKPlugin.initializeSDK(configuration, success, failure);
```

### Set User Details {#set-user-details}

The setUserDetails function is used to set user details for doing a checkout.

|    Parameter    |   Type   |                            Description                             |
|-----------------|----------|--------------------------------------------------------------------|
| userDetails     | Object   | An object of user details including email and phone number detail. |
| successCallback | Function | Called if the user details set successfully.                       |
| errorCallBack   | Function | Called if the user details failed to set.                          |

##### Callback parameters {#callback-parameters-1}

* successCallback - This function will not have any parameters.
* errorCallback - The parameter for this function is an object of type error (see below).

**errors**

|   Parameter   |  Type   |               Description                |
|---------------|---------|------------------------------------------|
| error.code    | Integer | Error code.                              |
| error.message | String  | Message describing the cause of failure. |

Example
* Javascript

```Javascript
var merchantSDKPlugin = cordova.require("cordova_Plugin_MerchantSDKPlugin.MerchantSDKPlugin");

var success = function() {
}

var failure = function(error) {
}

merchantSDKPlugin.setUserDetails(userDetails,success,failure);
```

### Get Masterpass Button {#get-masterpass-button}

The **getMasterpassButton** function is used to get a Masterpass button. The Masterpass button will have its own style and click event handler. No explicit calls are required to initiate checkout.

|           Parameters            |   Type   |                                                                                                                                                        Description                                                                                                                                                         |
|---------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| checkoutRequest                 | Object   | An object describing relevant specific options for all target platforms.                                                                                                                                                                                                                                                   |
| behavior                        | Integer  | Used to decide flow behavior at the time of Checkout. Available behaviors are: 0 for Default flow, 1 for Web flow, 2 for Pairing without checkout flow, 3 for Pairing with checkout flow. Note: This parameter is used only on the Android platform, iOS will ignore it (for clarity you may set this value to 0 for iOS). |
| masterpassButtonSuccessCallback | Function | This will be called after successful creation of a Masterpass button object.                                                                                                                                                                                                                                               |
| checkoutSuccessCallback         | Function | This will be called after a successful checkout.                                                                                                                                                                                                                                                                           |
| errorCallback                   | Function | This will be called if an error occurs while creating button or performing checkout.                                                                                                                                                                                                                                       |

Note: To support app to web checkout in iOS, you will need to handle custom URL schemes. See [Handling Custom URL Schemes](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/mobile-integration/masterpass-merchant-cordova-sdk-plug-in-for-ios-and-android/index.md#handling-custom-url-schemes) in this guide. The attributes of checkoutRequest are described below:

##### checkoutRequest {#checkoutrequest}

|       Parameter       |  Type   |                                                                                                                                                     Description                                                                                                                                                      |
|-----------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| allowedNetworkTypes   | Array   | List of strings objects specifying types of card accepted during checkout. Available card types are `MASTER`, `VISA`, `AMEX`, `DISCOVER`, `DINERS`. Card types are case sensitive.                                                                                                                                   |
| amount                | Object  | The amount object provides the total to be charged, and in what currency.                                                                                                                                                                                                                                            |
| cartId                | String  | This specifies the cart id to be used during checkout.                                                                                                                                                                                                                                                               |
| checkoutId            | String  | Checkout id based on user checkout environment and configuration (received while registering the merchant application on the Masterpass portal).                                                                                                                                                                     |
| merchantUserId        | String  | An ID provided by a merchant partner to Masterpass for express checkout pairing purposes. The merchant will receive their merchant user id while registering the merchant application on the Masterpass portal. Note: This is optional for web and wallet checkout, mandatory for pairing with and without checkout. |
| isShippingRequired    | Boolean | (Optional) True if shipping is required.                                                                                                                                                                                                                                                                             |
| merchantName          | String  | (Optional) This specifies the name of a merchant.                                                                                                                                                                                                                                                                    |
| tokenization          | Object  | (Optional) Contains the parameters to indicate a merchant partner's support of tokenized card details. This provides the ability to pass the unpredictableNumber and cryptoOptions. The attributes of tokenization are described below.                                                                              |
| suppress3DS           | Boolean | (Optional) The property used to describe the state of 3DS required. Note: Boolean values must be sent as string, within double quotes (i.e., "true" or "false").                                                                                                                                                     |
| shippingProfileId     | String  | (Optional) The identifier representing the merchant's supported shipping countries and/or subdivisions.                                                                                                                                                                                                              |
| callbackUrl           | String  | The callbackUrl for the merchant if it's different to the one configured through the merchant portal.                                                                                                                                                                                                                |
| cvc2support           | Boolean | Whether a merchant supports a dynamic cvc code used for Dynamic Token Verification.                                                                                                                                                                                                                                  |
| validityPeriodMinutes | Integer | Validity period for DTV code in minutes (also known as UCAF Bypass)                                                                                                                                                                                                                                                  |

The objects used in the **checkoutRequest** are described below:

##### amount {#amount}

|  Parameter   |          Type           |                                                                                                                    Description                                                                                                                     |
|--------------|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| total        | Number (floating point) | Total to be used for transaction. The value may have precision up to 2 decimal places. For example, 12.55 is a valid amount (representing $12.55 if USD is the currency), while 12.456 will not be considered as valid total (behavior undefined). |
| currencyCode | String                  | This specifies the currency used, for example `USD`.                                                                                                                                                                                               |

##### tokenization {#tokenization}

|      Parameter      |  Type  |                                     Description                                      |
|---------------------|--------|--------------------------------------------------------------------------------------|
| unpredictableNumber | String | This specifies randomly generated string.                                            |
| cryptoOptions       | Object | The cryptoOptions object provides arrays of the formats provided by different cards. |

##### cryptoOptions {#cryptooptions}

| Parameter  |  Type  |                                   Description                                   |
|------------|--------|---------------------------------------------------------------------------------|
| mastercard | Object | The mastercard object provides an array of the formats supported by Mastercard. |
| visa       | Object | The visa object provides an array of the formats supported by Visa.             |

The mastercard and visa objects are described below:

##### mastercard {#mastercard}

| Parameter | Type  |                                  Description                                   |
|-----------|-------|--------------------------------------------------------------------------------|
| format    | Array | List of formats supported by Mastercard. Available formats are: "UCAF", "ICC". |

##### visa {#visa}

| Parameter | Type  |                             Description                             |
|-----------|-------|---------------------------------------------------------------------|
| format    | Array | List of formats supported by Visa. Available formats are: "TAVV"\`. |

#### Callback parameters {#callback-parameters-2}

The call back parameters are as follows:

##### masterpassButtonSuccessCallback {#masterpassbuttonsuccesscallback}

|    Parameter     | Type |                                                       Description                                                        |
|------------------|------|--------------------------------------------------------------------------------------------------------------------------|
| masterpassButton | ;    | HTML `input` element with `type` attribute as `image`. This will need to be added to the UI of the Merchant application. |

##### checkoutSuccessCallback {#checkoutsuccesscallback}

The parameter for this function is an object of type **checkoutResponse**.

##### checkoutResponse {#checkoutresponse}

The checkout responses for Android and iOS are as follows:

|      Parameter       |       Type       |                                                   Description                                                   |
|----------------------|------------------|-----------------------------------------------------------------------------------------------------------------|
| flow                 | Number (integer) | Indicates flow behavior used for checkout. Available behaviors are: 1 for Web flow, 4 for Pairing flow.         |
| transactionId        | String           | Transaction Id generated after checkout.                                                                        |
| pairingTransactionId | String           | Pairing transaction Id in case of pairing with and without checkout.                                            |
| totalAmount          | Object           | The total to be charged, and in what currency (see the amountobject). Note: totalAmount is not always provided. |
| cartId               | String           | This property contains the cart id from the merchant checkout service.                                          |
| checkoutResourceURL  | String           | This property contains the checkout resource URL from the merchant checkout service.                            |

##### errorCallBack {#errorcallback}

The parameter for this function is an object of type **error**.

##### Example {#example}

* Javascript

```Javascript
var merchantSDKPlugin = cordova.require("cordova_Plugin_MerchantSDKPlugin.MerchantSDKPlugin");

var getMasterpassButtonSuccess = function(masterpassButton) {
}

var checkoutSuccess = function(checkoutResponse){
}

var failure = function(error) {
}

merchantSDKPlugin.getMasterpassButton(checkoutRequest, 0, getMasterpassButtonSuccess, checkoutSuccess,failure);
```

### Pairing With Express Checkout {#pairing-with-express-checkout}

The Pairing With Express Checkout function is used to perform web-based (App to Web) express paring with checkout.
Note: To support app to web checkout in iOS, you will need to handle custom URL schemes. See the Handling Custom URL Schemes section at the beginning of this guide for details.

### Parameters (Pairing With Express Checkout) {#parameters-pairing-with-express-checkout}

|    Parameters     |   Type   |                                                                      Description                                                                       |
|-------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| checkoutRequest   | Object   | All available attributes of the checkoutRequest are described by this object. See the documentation of the checkout request above for details.         |
| isCheckoutEnabled | Boolean  | If true then pairing has to be performed during checkout. Note: Boolean values must be sent as string, within double quotes (i.e., "true" or "false"). |
| successCallback   | Function | This will be called after a successful checkout.                                                                                                       |
| errorCallback     | Function | This will be called if an error occurs while creating a button or performing a checkout.                                                               |

Callback parameters (Pairing With Express Checkout)

##### successCallback {#successcallback}

The parameter for this function is an object of type **checkoutResponse**.

##### errorCallback {#errorcallback-1}

The parameter for this function is an object of type **error**.

### Example (Pairing With Express Checkout) {#example-pairing-with-express-checkout}

* Javascript

```Javascript
var merchantSDKPlugin = cordova.require("cordova_Plugin_MerchantSDKPlugin.MerchantSDKPlugin");

var success = function(checkoutResponse) {

}

var failure = function(error) {

}

merchantSDKPlugin.webCheckout(checkoutRequest, success, failure);
```

### Pairing for Express Checkout {#pairing-for-express-checkout}

The **doPairing** function is used to get the pairing transaction id (with or without checkout). This pairing transaction id will be used to perform express checkout.

#### Parameters {#parameters-1}

|     Parameter     |   Type   |                                                                      Description                                                                       |
|-------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| checkoutRequest   | Object   | All available attributes of checkoutRequest are as described in the Checkout Request section of the Get Masterpass Button flow description.            |
| isCheckoutEnabled | Boolean  | If true then pairing has to be performed during checkout. Note: Boolean values must be sent as string, within double quotes (i.e., "true" or "false"). |
| successCallback   | Function | This will be called after successful pairing.                                                                                                          |
| errorCallback     | Function | This will be called if an error occurs while pairing.                                                                                                  |

### Callback Parameters (Express Pairing) {#callback-parameters-express-pairing}

##### successCallback {#successcallback-1}

The parameter for this function is an object of type **checkoutResponse**.

##### errorCallback {#errorcallback-2}

The parameter for this function is an object of type **error**.
* Javascript

```Javascript
var merchantSDKPlugin = cordova.require("cordova_Plugin_MerchantSDKPlugin.MerchantSDKPlugin");

var success = function(checkoutResponse) {

}

var failure = function(error) {

}

merchantSDKPlugin.doPairing(false, checkoutRequest, success, failure);
```

### Add Masterpass Payment Method {#add-masterpass-payment-method}

The **Add Payment Method** function is used to add Masterpass Payment Method using any bank issued Debit / Credit Card which will be used further to do checkout.

#### Parameters {#parameters-2}

|    Parameter     |   Type   |                                                 Description                                                  |
|------------------|----------|--------------------------------------------------------------------------------------------------------------|
| allowedCardTypes | String   | Json array of allowed network or card types as String in capital letter i.e. MASTER, VISA, AMEX, DINERS etc. |
| checkoutId       | String   | Merchant checkout identifier received when merchant onboarded for Masterpass.                                |
| merchantUserId   | String   | An ID provided by a merchant to Masterpass for express checkout pairing purpose.                             |
| successCallback  | Function | This will be called after successful pairing.                                                                |
| errorCallback    | Function | This will be called if an error occurs while pairing.                                                        |

#### Callback Parameters (Add Masterpass Payment Method) {#callback-parameters-add-masterpass-payment-method}

##### successCallback {#successcallback-2}

The parameter for this function is an object of type **MasterpassPaymentMethod**

##### errorCallback {#errorcallback-3}

The parameter for this function is an object of type **error**.
* Javascript

```Javascript
var merchantSDKPlugin = cordova.require("cordova_Plugin_MerchantSDKPlugin.MerchantSDKPlugin");

var success = function(paymentMethodResponse) {

}

var failure = function(error) {

}

merchantSDKPlugin.addMasterpassPaymentMethod(allowedCardTypes,checkoutId,merchantUserId,success,failure);
```

### Payment Method Checkout {#payment-method-checkout}

The **Payment Method Checkout** function is used to perform MEX (Merchant Embedded Experience) checkout with added Masterpass Payment Method.  

|      Parameters       |   Type   |                                                                  Description                                                                   |
|-----------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------|
| checkoutRequest       | Object   | All available attributes of the checkoutRequest are described by this object. See the documentation of the checkout request above for details. |
| selectedPaymentMethod | Object   | MasterpassPaymentMethod object which got in the success of addMasterpassPaymentMethod for doing checkout with the added payment method.        |
| successCallback       | Function | This will be called after a successful checkout.                                                                                               |
| errorCallback         | Function | This will be called if an error occurs while creating a button or performing a checkout.                                                       |

#### Callback parameters (Payment Method Checkout) {#callback-parameters-payment-method-checkout}

##### successCallback {#successcallback-3}

The parameter for this function is an object of type **checkoutResponse**.

##### errorCallback {#errorcallback-4}

The parameter for this function is an object of type **error**.

### Example (Payment Method Checkout) {#example-payment-method-checkout}

* Javascript

```Javascript
var merchantSDKPlugin = cordova.require("cordova_Plugin_MerchantSDKPlugin.MerchantSDKPlugin");

var success = function(checkoutResponse) {

}

var failure = function(error) {

}

merchantSDKPlugin.paymentMethodCheckout(checkoutRequest, selectedPaymentMethod, success, failure);
```