C# SDK Configurations

Prerequisites

1. Visual Studio Professional Edition 2013 or higher
2. .NET Framework 4.5.2

Integrate the MasterPass SDK

1. Open your project. In Solution Explorer, open "Web Project".

2. Right-click "reference" and select "ManageNugetPackages".

3. Search for the package with ID name "Com.MasterCard.Masterpass.Merchant". Download and install this package.

4. Download and install the Com.MasterCard.Sdk.Core package.

Configurations

Prior to completing this step, the developer must have uploaded or generated a PEM encoded Certificate Request File, and generated a consumer key in the Merchant Portal as part of the onboarding process.

Use the MasterCardApiConfiguration to set your environment as either sandbox or production. Set the hostname URL according to the MasterPass environment you want to connect to. Use "https://api.mastercard.com" for production, and "https://sandbox.api.mastercard.com" for sandbox.

private void SetConfigurations() 
{
	string hostUrl = ConfigurationManager.AppSettings["ApiHostUrl"];
	string consumerKey = ConfigurationManager.AppSettings["ConsumerKey"];
	string KeystorePath = Server.MapPath(ConfigurationManager.AppSettings["KeystorePath"]);
	string KeystorePassword = ConfigurationManager.AppSettings["KeystorePassword"];
	string IsSandbox = ConfigurationManager.AppSettings["IsSandbox"];
	var privateKey = new X509Certificate2(KeystorePath, KeystorePassword).PrivateKey;
	MasterCardApiConfiguration.Sandbox = Convert.ToBoolean(IsSandbox); //set as false for production
	MasterCardApiConfiguration.ConsumerKey = consumerKey;
	MasterCardApiConfiguration.PrivateKey = privateKey;
}

Optionally, use the ApiConfigBuilder instead of the MasterCardApiConfiguration to set the environment to a value other than sandbox or production. See the following sample code to set the environment and use in an API service call.

public const string ConfigName = "Stage";
private void SetConfigurations() 
{
	string hostUrl = ConfigurationManager.AppSettings["ApiHostUrl"];
	string consumerKey = ConfigurationManager.AppSettings["ConsumerKey"];
	string keystorePath = Server.MapPath(ConfigurationManager.AppSettings["KeystorePath"]); string keystorePassword = ConfigurationManager.AppSettings["KeystorePassword"];
	string IsSandbox = ConfigurationManager.AppSettings["IsSandbox"];
	var privateKey = new X509Certificate2(keystorePath, keystorePassword).PrivateKey;

	// Register the Environment Configuration with Name "Stage". 
	var stageApiConfig = new ApiConfigBuilder().Name(ConfigName).HostUrl(hostUrl).ConsumerKey(consumerKey).PrivateKey(privateKey).Build();
}

If you choose to use the ApiConfigBuilder instead of the MasterCardApiConfig to set your environment, you will need to pass your config as a parameter when making service calls. See the RequestTokenApi service call example below.

RequestTokenApi service call using MasterCardApiConfig

string callback_url = "https://www.somemerchant.com/checkoutconfirm.htm";
RequestTokenResponse requestTokenResponse = RequestTokenApi.Create(callback_url);
string request_token = requestTokenResponse.OauthToken;

RequestTokenApi service call using ApiConfigBuilder

// Call the service with the registered configuration.
string callback_url = "https://www.somemerchant.com/checkoutconfirm.htm";
RequestTokenResponse requestTokenResponse = RequestTokenApi.Create(callback_url, MasterCardApiConfiguration.GetConfig(ConfigName));
string request_token = requestTokenResponse.OauthToken;

Exception Handling

The Base SDK contains all of the exception classes that will be used across the Base and Client SDKs. All exceptions thrown are Runtime Exceptions. The table below details the different exception classes.

Logging

Set the reference configuration shown below in the App.config or Web.config of your application.

slf4net Configuration App.config / Web.config

Simple Logging

<?xml version="1.0" encoding="utf-8"?> 
<configuration>  
  <configSections>     
    <section name="slf4net" type="slf4net.Configuration.SlfConfigurationSection, slf4net" />
  </configSections>   
  <slf4net>     
    <factory type="slf4net.Factories.SimpleLoggerFactory, slf4net.Simple">       
      <factory-data>
        <logger name="TraceLogger" type="slf4net.TraceLogger, slf4net.Simple" />
      </factory-data>
    </factory>
  </slf4net>

</configuration>

NLog

<?xml version="1.0" encoding="utf-8"?>

<configuration>
  <configSections>
    <section name="slf4net" type="slf4net.Configuration.SlfConfigurationSection, slf4net" />
  </configSections>
  <slf4net>
    <factory type="slf4net.NLog.NLogLoggerFactory, slf4net.NLog" />
  </slf4net>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="NLog" publicKeyToken="5120e14c03d0593c" culture="neutral" />
        <bindingRedirect oldVersion="0.0.0.0-4.0.0.0" newVersion="4.0.0.0" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>

</configuration>

Log4Net

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="slf4net" type="slf4net.Configuration.SlfConfigurationSection, slf4net" />
  </configSections>
  <slf4net>
    <factory type="slf4net.log4net.Log4netLoggerFactory, slf4net.log4net">

      <factory-data>
        <configFile value="log4net.config" />

        <watch value="true" />
      </factory-data>
    </factory>
  </slf4net>
</configuration>

Logging Framework Configuration File

NLog

NLog.config required in application to set the NLog framework specific configuration.

<?xml version="1.0" encoding="utf-8"?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target name="FileLogger" xsi:type="File" fileName="MasterPass-SDK.log" layout="${longdate} ${level:upperCase=true} ${message} (${callsite:includSourcePath=true})" />

    <target xsi:type="Trace" name="TraceLogger" />
  </targets>

  <rules>
    <logger name="*" writeTo="FileLogger,TraceLogger" minlevel="Trace" />
  </rules>
</nlog>

Log4Net

log4net.config required in application to set the log4net framework specific configuration.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <log4net>
    <appender name="DebugConsole" type="log4net.Appender.DebugAppender">
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date %-5level: %message%newline" />
      </layout>
    </appender>
    <appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
      <file value="MasterPass-SDK.log" />
      <appendToFile value="false" />
      <rollingStyle value="Size" />
      <maxSizeRollBackups value="10" />
      <maximumFileSize value="50MB" />
      <staticLogFileName value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date %-5level[%logger]: %message%newline" />
      </layout>
    </appender>
    <root>
      <level value="ALL" />
      <appender-ref ref="DebugConsole" />
      <appender-ref ref="RollingFileAppender" />
    </root>
  </log4net>
</configuration>

Web.Config Sample Code

An example of a Web.Config file with the required configurations is shown below.

<?xml version="1.0" encoding="utf-8"?>

<!--
  For more information on how to configure your ASP.NET application, please visit
  http://go.microsoft.com/fwlink/?LinkId=152368
  -->

<configuration>

  <configSections>

    <section name="slf4net" type="slf4net.Configuration.SlfConfigurationSection, slf4net" />

  </configSections>

  <slf4net>

    <factory type="slf4net.log4net.Log4netLoggerFactory, slf4net.log4net">

      <factory-data>

        <configFile value="log4net.config" />

        <watch value="true" />

      </factory-data>

    </factory>

  </slf4net>

  <appSettings>

    .....
	
    <!-- 
      
    Following are the settings used by the Wallet Sample Application

    which are used to connect/interact with the Wallet API.

    -->

    <add key="ApiHostUrl" value="https://sandbox.api.mastercard.com" />

    <add key="CallbackDomain" value="http://localhost:9090" />

    <add key="CallbackPath" value="/O3_Callback" />

    <add key="ConnectedCallbackPath" value="/O3_Callback?connect=true" />

    <add key="ConsumerKey" value="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c!414f4859446c4a366c726a327474695545332b353049303d" />

    <add key="CheckoutIdentifier" value="a4a6x1ywxlkxzhensyvad1hepuouaesuv" />

    <add key="KeystorePath" value="~/Certs/Sandbox/414f4859446c4a366c726a327474695545332b353049303d.p12" />

    <add key="KeystorePassword" value="changeit" />

    <add key="IsSandbox" value="true" />
  </appSettings>

  
  .....


</configuration>

Ruby SDK Configurations

Prerequisites

Ruby 2.2 or higher is required.

Windows

To install DevKit along with Ruby, download DevKit from http://rubyinstaller.org/downloads/ and run it to extract it to a location. Then, execute rubydk.rb init and rubydk.rb install from that location to bind DevKit to the Ruby installations in your path.

cd <DEVKIT_INSTALL_DIR>
C:\DevKit>rubydk.rbinit
C:\DevKit>rubydk.rbinstall
C:\DevKit> gem source -a http://rubygems.org/

Linux

Ruby Version Manager (RVM) is the recommended way to manage Ruby versions and gems because it is popular, well-supported, and full-featured.

$sudo apt-get install curl

$ \curl -sSL https://get.rvm.io | bash 

$rvm install <ruby version>

rvmuse<ruby version>

Mac OS

While Ruby comes pre-installed on a Mac, it is recommended to install Ruby using Ruby Version Manager (RVM) instead.

$ \curl -L https://get.rvm.io | bash

cd ~/
sudo vim .bash_profile

rvm install <Ruby Version>

Integrate the MasterPass SDK

Developers may either install the MasterPass SDK gem locally, or from RubyGems.org.

Installing gems locally

gem install mastercard_code_sdk-1.0.0.gem
gem install mastercard_masterpass_merchant-1.0.0.gem

Installing gems from RubyGems.org

gem install mastercard_masterpass_merchant [options]

Installing mastercard_masterpass_merchant gem automatically installs the following dependencies:

1. mastercard_core_sdk
2. roxml
3. logging
4. mime-types

Options

--platform PLATFORM

-v, --version VERSION

--[no-]prerelease

Configurations

Prior to completing this step, the developer must have uploaded or generated a PEM encoded Certificate Request File, and generated a consumer key in the Merchant Portal as part of the onboarding process.

Use the MasterCardApiConfiguration to set the environment as either sandbox or production, as shown in the code below:

MasterCardApiConfiguration.consumer_key = <Consumer Key>
MasterCardApiConfiguration.private_key = <Private Key>
MasterCardApiConfiguration.sandbox = false  #By default SANDBOX environment is set, Set sandbox to false to use Production environment.

Optionally, use the ApiConfigBuilder instead of the MasterCardApiConfig to set the environment to a value other than sandbox or production.

config = ApiConfigBuilder.new.name(<Environment Name>).consumer_key(<Consumer Key>).private_key(<Private Key>).host_url(<Host URL>).build

If you choose to use the ApiConfigBuilder to set your environment, you will need to pass your config object as a parameter when making service calls. See the RequestTokenApi service call sample code below.

RequestTokenApi service call using MasterCardApiConfig

request_token_response = RequestTokenApi.create("http://localhost/techbuzz/#/callback/checkout") 

RequestTokenApi service call using ApiConfigBuilder

request_token_response = RequestTokenApi.create("http://localhost/techbuzz/#/callback/checkout", config)

Exception Handling

All error handling is implemented in the base SDK (masterpass_core_sdk). Error models are present in both the base SDK and the checkout SDK (mastercard_masterpass_merchant). The table below lists the various error classes used across the MasterPass SDK and their responsibilities.

The custom error object wraps error details such as source, description, recoverable, and reasons_code. The error object raised can be rescued as followed:

begin

  #TODO: Merchant checkout SDK call.

  rescue SDKResponseError => e
 
    errors = e.errors_object
 
    errors.error.each do |error|

     	 #Retrieve the error details(source, description, recoverable and reason_code) from Error object.

     	 	 error_message = "Source:"+ error.source +"\n" +
     	 	 "ReasonCode:"+error.reason_code +"\n" +
     	 	 "Description:"+error.description +"\n" +
     	 	 "Recoverable:"+error.recoverable

     	  puts error_message

    end

  end

Logging

Logging is implemented using gem logging, which features a hierarchical logging system, custom level names, multiple output destinations per log event, custom formatting, and other features. The developer must set the log level and the log destination output file:

require 'logging'
Logging.logger.root.level = :debug
Logging.logger.root.appenders = Logging.appenders.file(<Filename>)

PHP SDK Configurations

Prerequisites

Windows 7 Environment

1. XAMPP Version 1.8.3 (This setup will install PHP and Apache)
2. Microsoft Visual C++ 2008 Redistributable package
3. Ensure openssl and curl extensions are enabled in php.ini.
4. Apache rewrite module should be enabled via httpd.conf.
5. Download required http client file guzzle.phar from https://github.com/guzzle/guzzle/releases/tag/6.0.0 and include in your file/project:

   include_once 'guzzle.phar';

6. For logging implementation, download Log4PHP library. Download and extract folder, take source code which is located in /src/main/php. Rename php folder to “logger” and keep it in project folder.
7. Recommend using PHPStorm or similar IDE in order to access .phar contents.

OS X Environment

Coming soon

Integrate the MasterPass SDK

Include MasterCardCoreSDK.phar and MasterCardMasterPassMerchant.phar in your file/project:

include_once 'MasterCardCoreSDK.phar';
include_once 'MasterCardClientSDK.phar';

Configuration

1. Get private key

Prior to completing this step, the developer must have uploaded or generated a PEM encoded Certificate Request File, and generated a consumer key in the Merchant Portal as part of the onboarding process.

public function getPrivateKey($keyId){
	$fileName = "example-file.p12";	// path to your p12 file
	$password = "password"		// your keystore password
	if (!$certStore = file_get_contents($fileName)) {
		return 'Error: Unable to read the cert file.';
	}
	if (openssl_pkcs12_read($certStore, $certInfo, "password")) {
		return $certInfo['pkey'];
	} 
	else {
		return 'Error: Unable to read the cert store.';
	}
}

2. Configure Environment

$hostUrl = "https://sandbox.api.mastercard.com";	// for sandbox
$hostUrl = "https://api.mastercard.com";		// for production

$apiConfigBuilder = new ApiConfigBuilder();
$apiConfigBuilder->setHostUrl($hostUrl);
$apiConfigBuilder->setConsumerKey("insert_consumerKey_here");
$apiConfigBuilder->setPrivateKey("insert_private_key_here");
$apiConfigBuilder->build();

Exception Handling

The following sample code demonstrates how to get the error details from an Error object.

try {
//Merchant checkout SDK call.
} catch (Exception $exception) {
	if ($exception instanceof SDKErrorResponseException) {
		$errors = $exception->getErrorResponse();
		$errorList = $errors->getError();
		foreach ($errorList as $error) { 
			$errorMessage = "Source:" . $error->getSource() . "\n" 
			. "ReasonCode:" . $error->getReasonCode() . "\n" . "Description:" 
			. $error->getDescription() . "\n" . "Recoverable:" . $error->getRecoverable();
		} 
	}
}

Logging

Implementation

include_once "logger/Logger.php";
Logger::configure("config.xml"); 		// Skip this step to load default configuration
$logger = Logger::getLogger('main');
$logger->info("Info message");
$logger->debug("Debug message");
$logger->error("Error message");
$logger->fatal("Fatal error");

Example Config.

<?xml version="1.0" encoding="utf-8" ?>
			<configuration xmlns="http://logging.apache.org/log4php/">
			    <appender name="default" class="LoggerAppenderDailyFile">
			        <layout class="LoggerLayoutPattern">
			            <param name="conversionPattern" value="%date %logger %-5level %msg%n" />
			        </layout>
						
			        <param name="file" value="logs/log-%s.log" />
			        <param name="datePattern" value="Y-m-d" />
			        <param name="append" value="true" />
			    </appender>

			    <root>
					<level value="TRACE" />
			        <appender_ref ref="default" />
			    </root>
			</configuration>

Standard Checkout Integration

1. Call Request Token Service

Call the Request Token Service to generate the request token that will be used to invoke the MasterPass Lightbox. Pass a callback_url that the browser will redirect to when the Lightbox closes.

The Request Token Service must be called before the consumer clicks the Buy with MasterPass button.

callback_url = "https://www.somemerchant.com/checkoutconfirm.htm"
request_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
request_token = request_token_response.oauth_token;

2. Call Shopping Cart Service

The Shopping Cart Service enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. This service requires the request token from Step 1.

Each shopping_cart_item must have a description, quantity, and value. Value is represented as an integer (for example, USD 100.00 is 10000), and is calculated as the cost of a single item multiplied by the quantity of that item. A shopping_cart_item may also have an optional image_url.

The Shopping Cart Service must be called before the consumer clicks the Buy with MasterPass button.

shopping_cart_request = MastercardMasterpassMerchant::ShoppingCartRequest.new(
    :o_auth_token => request_token,
    :shopping_cart => MastercardMasterpassMerchant::ShoppingCart.new(
        :currency_code => 'USD',
        :subtotal => '11900',
        :shopping_cart_item => [
            MastercardMasterpassMerchant::ShoppingCartItem.new(
                :description => 'One Item',
                :quantity => 1,
                :value => 1900
            ),
            MastercardMasterpassMerchant::ShoppingCartItem.new(
                :description => 'Five of an Item',
                :quantity => 5,
                :value => 10000,
                :image_url => 'http://somemerchant.com/someimage'
            )
        ]
    )
)

shopping_cart_response = MastercardMasterpassMerchant::Api::ShoppingCartApi.create(shopping_cart_request)

3. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant site and MasterPass. The origin_url identifies the origin of the page that will initialize the Lightbox. This service requires the request token from Step 1.

The Merchant Initialization Service must be called before the consumer clicks the Buy with MasterPass button.

merchant_init_request = MastercardMasterpassMerchant::MerchantInitializationRequest.new(
    :o_auth_token => request_token,
    :origin_url => 'https://somemerchant.com'
)

merchant_init_response = MastercardMasterpassMerchant::Api::MerchantInitializationApi.create(merchant_init_request)

4. Invoke MasterPass UI (Lightbox) for checkout

On the Checkout Page of the merchant's website, add the Buy with MasterPass button to your HTML (see MasterPass Branding to customize size and locale).

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png"/>

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>
 <!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->
 <!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

Invoke the MasterPass lightbox when the user clicks the Buy with MasterPass button.

<script type="text/javascript" language="Javascript"> 
    MasterPass.client.checkout({ 
         "requestToken":"insert_request_token_here",                      //required
         "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",//required
         "merchantCheckoutId":"insert_checkout_id_here",                  //required
         "allowedCardTypes":["master,amex,diners,discover,maestro,visa"], //optional 
         "version":"v6",                                                  //optional
         "successCallback": function(mpLightboxResponse){ ... },          //optional
         "failureCallback": function(mpLightboxResponse){ ... },          //optional
         "cancelCallback": function(mpLightboxResponse){ ... }            //optional
    });
</script>

• requestToken: The request token generated in Step 1.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the Merchant Onboarding process.
• allowedCardTypes: Card types accepted by the merchant (default is all card types).
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass flow ends successfully.
• failureCallback: The function that will be called if the MasterPass flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass flow.

5. Redirect to callback URL or call callback function

After the consumer completes checkout, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will be redirected to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

On Success

On Success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• checkout_resource_url: The API URL that will be used to retrieve checkout information in Step 7.
• oauth_verifier: The verifier token that is used to retrieve the access token in Step 6.
• oauth_token: The request token that is used to retrieve the access token in Step 6. This token has the same value as the request token that is generated in Step 1.

Example Callback URL (Success)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass\%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw
&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13
&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc

Example Callback URL (Cancel)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

Example Callback Function (Success)

function handleCallbackSuccess (data) {
    callYourServerWith(data.oauth_token, data.oauth_verifier, data.checkout_resource_url);
}

6. Call Access Token Service

If the checkout was completed successfully, call the Access Token Service to retrieve an access token. You will need the request token and the verifier token received in Step 5.

access_token_response = MastercardCoreSdk::Api::AccessTokenApi.create(verifier_token, request_token)
access_token = access_token_response.oauth_token
}

7. Retrieve payment, shipping data, rewards and 3DS details

Use the checkout resource URL received in Step 5 and the access token from Step 6 to retrieve the constomer’s payment, shipping, reward and 3-D Secure information from MasterPass.

start_index = checkout_resource_url.rindex('/') + 1
end_index = checkout_resource_url.index('?').nil? ? -1 : checkout_resource_url.index('?')
path_id = checkout_resource_url[start_index..end_index]

checkout = MastercardMasterpassMerchant::Api::CheckoutApi.show(path_id, access_token)
card = checkout.card
billing_address = card.billing_address
contact = checkout.contact
auth_options = checkout.authentication_options
precheckout_transaction_id = checkout.pre_checkout_transaction_id
reward_program = checkout.reward_program
shipping_address = checkout.shipping_address
transaction_id = checkout.transaction_id
wallet_id = checkout.wallet_id

8. Process payment through a payment gateway

Using the information retrieved in Step 7, process the payment through the merchant's payment gateway.

9. Log transactions with MasterPass

After the payment has been processed in Step 8, make a service call to communicate the result of the transaction to MasterPass.

merchant_transactions = MastercardMasterpassMerchant::MerchantTransactions.new(
    :merchant_transactions => [
        MastercardMasterpassMerchant::MerchantTransaction.new(
            :transaction_id => 4549794,
            :consumer_key => '0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d',
            :currency => 'USD',
            :order_amount => 1800,
            :transaction_status => 'Success',
            :approval_code => '888888',
            :pre_checkout_transaction_id => 'a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947',
            :express_checkout_indicator => false,
            :purchase_date => '2016-06-23T15:09:32+00:00'
        )
    ]
)

merchant_trans_response = MastercardMasterpassMerchant::Api::PostbackApi.create(merchant_transactions)

Standard Checkout Integration

1. Call Request Token Service

Call the Request Token Service to generate the request token that will be used to invoke the MasterPass Lightbox. Pass a callbackUrl that the browser will redirect to when the Lightbox closes.

The Request Token Service must be called before the consumer clicks the Buy with MasterPass button.

$callbackUrl = "https://www.somemerchant.com/checkoutconfirm.htm";
$requestTokenResponse = RequestTokenApi::create($callbackUrl);
$requestToken = $requestTokenResponse->getOauthToken();

2. Call Shopping Cart Service

The Shopping Cart Service enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. This service requires the request token from Step 1.

Each ShoppingCartItem must have a description, quantity, and value. Value is represented as an integer (for example, USD 100.00 is 10000), and is calculated as the cost of a single item multiplied by the quantity of that item. A ShoppingCartItem may also have an optional ImageURL.

The Shopping Cart Service must be called before the consumer clicks the Buy with MasterPass button.

//Build Out ShoppingCartRequest object
$shoppingCartItem1 = new ShoppingCartItem(
	array(
		"Value" => 700,
		"Description" => "This is one item",
		"Quantity" => 1,
		"ImageURL" => "https://somemerchant.com/someimage"
	)
);

$shoppingCartItem2 = new ShoppingCartItem(
	array(
		"Value" => 300,
		"Description" => "This is another item",
		"Quantity" => 1,
		"ImageURL" => "https://somemerchant.com/someotherimage"
		)
);

$shoppingCart = new ShoppingCart(
	array(
		"CurrencyCode" => "USD",
		"Subtotal" => 1000,
		"ShoppingCartItem" => array($shoppingCartItem1, $shoppingCartItem2)
	)
);

$shoppingCartRequest = new ShoppingCartRequest(
	array(
		"OAuthToken" => $requestToken,
		"OriginUrl" => $callbackDomain,
		"ShoppingCart" => $shoppingCart,
	)
);

//Call the ShoppingCartService with required params
$shoppingCartResponse = ShoppingCartApi::create($shoppingCartRequest);

3. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant site and MasterPass. The OriginUrl identifies the origin of the page that will initialize the Lightbox. This service requires the request token from Step 1.

The Merchant Initialization Service must be called before the consumer clicks the Buy with MasterPass button.

//Create an instance of MerchantInitializationRequest
$merchantInitializationRequest = new MerchantInitializationRequest(
	array(
		"OriginUrl" => "https://somemerchant.com",
		"OAuthToken" => $requestToken
	)
);

//Call the MerchantInitializationApi with required params
$merchantInitializationResponse = MerchantInitializationApi::create($merchantInitializationRequest);

4. Invoke MasterPass UI (Lightbox) for checkout

On the Checkout Page of the merchant's website, add the Buy with MasterPass button to your HTML (see MasterPass Branding to customize size and locale).

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png"/>

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>
 <!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->
 <!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

Invoke the MasterPass lightbox when the user clicks the Buy with MasterPass button.

<script type="text/javascript" language="Javascript"> 
    MasterPass.client.checkout({ 
         "requestToken":"insert_request_token_here",                      //required
         "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",//required
         "merchantCheckoutId":"insert_checkout_id_here",                  //required
         "allowedCardTypes":["master,amex,diners,discover,maestro,visa"], //optional 
         "version":"v6",                                                  //optional
         "successCallback": function(mpLightboxResponse){ ... },          //optional
         "failureCallback": function(mpLightboxResponse){ ... },          //optional
         "cancelCallback": function(mpLightboxResponse){ ... }            //optional
    });
</script>

• requestToken: The request token generated in Step 1.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the Merchant Onboarding process.
• allowedCardTypes: Card types accepted by the merchant (default is all card types).
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass flow ends successfully.
• failureCallback: The function that will be called if the MasterPass flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass flow.

5. Redirect to callback URL or call callback function

After the consumer completes checkout, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will be redirected to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

On Success

On Success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• checkout_resource_url: The API URL that will be used to retrieve checkout information in Step 7.
• oauth_verifier: The verifier token that is used to retrieve the access token in Step 6.
• oauth_token: The request token that is used to retrieve the access token in Step 6. This token has the same value as the request token that is generated in Step 1.

Example Callback URL (Success)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass\%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw
&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13
&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc

Example Callback URL (Cancel)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

Example Callback Function (Success)

function handleCallbackSuccess (data) {
    callYourServerWith(data.oauth_token, data.oauth_verifier, data.checkout_resource_url);
}

6. Call Access Token Service

If the checkout was completed successfully, call the Access Token Service to retrieve an access token. You will need the request token and the verifier token received in Step 5.

$accessTokenResponse = AccessTokenApi::create(requestToken, verifierToken);
$accessToken = $accessTokenResponse->getOauthToken();

7. Retrieve payment, shipping data, rewards and 3DS details

Use the checkout resource URL received in Step 5 and the access token from Step 6 to retrieve the constomer’s payment, shipping, reward and 3-D Secure information from MasterPass.

$explodedURL = explode("/", $checkoutResourceUrl);
$checkoutId = array_pop($explodedURL);
if(strpos($checkoutId, "?") !== false){
    $checkoutId = explode($checkoutId, "?")[0];
}

$logger->info($checkoutId);

$checkout = CheckoutApi::show($checkoutId, $accessToken);

$card = $checkout->getCard();
$billingAddress = $card->getBillingAddress();
$contact = $checkout->getContact();
$authOptions = checkout->getAuthenticationOptions(); 
$preCheckoutTransactionId = checkout->getPreCheckoutTransactionId(); 
$rewardProgram = checkout->getRewardProgram(); 
$shippingAddress = checkout->getShippingAddress();
$transactionId = checkout->getTransactionId();
$walletId = checkout->getWalletID();

8. Process payment through a payment gateway

Using the information retrieved in Step 7, process the payment through the merchant's payment gateway.

9. Log transactions with MasterPass

After the payment has been processed in Step 8, make a service call to communicate the result of the transaction to MasterPass.

//Create an instance of MerchantTransactions

$merchantTransaction = new MerchantTransaction(
	array(
		"TransactionId" => "4549794",
		"ConsumerKey" => "0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d", //generated during onboarding process
		"Currency" => "USD",
		"OrderAmount" => 500, // total charged to card
		"TransactionStatus" => "Success",
		"ApprovalCode" => "888888", // authorization code returned by payment gateway
		"PrecheckoutTransactionId" => "a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947",
		"ExpressCheckoutIndicator" => false,
		"PurchaseDate" => date("Y/m/d H:i:s")
	)
);
$request = new MerchantTransactions(array("MerchantTransactions" => array($merchantTransaction)));

//Call the PostbackService with required params
$response = PostbackApi::create($request);

Connected Checkout Integration

Pairing During Checkout

1. Call Request Token Service (2 times)

Call the Request Token Service twice. The first call generates a pairing request token, which will be used to gain the long access token needed to pair the consumer's wallet and merchant account.

The second call generates a checkout request token that will be used to invoke the MasterPass Lightbox. Pass a callback_url that the browser will redirect to when the Lightbox closes.

The Request Token Service calls must be made before the consumer clicks the Buy with MasterPass button.

string callback_url = "https://www.somemerchant.com/pairingcomplete.htm";
RequestTokenResponse requestTokenResponse = RequestTokenApi.Create(callback_url);
string pairing_request_token = requestTokenResponse.OauthToken;
RequestTokenResponse requestTokenResponse = RequestTokenApi.Create(callback_url);
string request_token = requestTokenResponse.OauthToken;

2. Call Shopping Cart Service

The Shopping Cart Service enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. This service requires the checkout request token from Step 1.

Each ShoppingCartItem must have a description, quantity, and value. Value is represented as an integer (for example, USD 100.00 is 10000), and is calculated as the cost of a single item multiplied by the quantity of that item. A ShoppingCartItem may also have an optional imageURL.

The Shopping Cart Service must be called before the consumer clicks the Buy with MasterPass button.

//Create an instance of ShoppingCartRequest
ShoppingCartRequest shoppingCartRequest = new ShoppingCartRequest();
ShoppingCart shoppingCart = new ShoppingCart();
List<ShoppingCartItem> shoppingCartItems = new List<ShoppingCartItem>();
shoppingCartItems.Add(new ShoppingCartItem
{
	Value = 1900L,
	Description = "This is one item",
	Quantity = 1
});
shoppingCartItems.Add(new ShoppingCartItem
{
    ImageURL = "https://somemerchant.com/someimage",
    Value = 10000L,
    Description = "Five items",
    Quantity = 5
});

shoppingCart.Subtotal = 11900L;
shoppingCart.CurrencyCode = "USD";
shoppingCart.ShoppingCartItem = shoppingCartItems;

shoppingCartRequest.ShoppingCart = shoppingCart;
shoppingCartRequest.OAuthToken = request_token;

//Call the ShoppingCartService with required params
ShoppingCartResponse shoppingCartResponse = ShoppingCartApi.Create(shoppingCartRequest);

3. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant and MasterPass. The originUrl identifies the origin of the page that will initialize the Lightbox. This service requires the checkout request token from Step 1.

The Merchant Initialization Service must be called before the consumer clicks the Buy with MasterPass button.

//Create an instance of MerchantInitializationRequest
MerchantInitializationRequest merchantInitializationRequest = new MerchantInitializationRequest
{
    OriginUrl = "https://somemerchant.com",
    OAuthToken = request_token
};

//Call the MerchantInitializationApi with required params
MerchantInitializationResponse merchantInitializationResponse = MerchantInitializationApi.Create(merchantInitializationRequest);

4. Invoke MasterPass UI (Lightbox) for checkout

On the Checkout Page of the merchant's website, add the Buy with MasterPass button to your HTML (see MasterPass Branding to customize size and locale).

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png"/>

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment.

<!-- url to jquery 1.10.2 -->
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
  <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
  <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

Invoke the MasterPass lightbox when the user clicks the Buy with MasterPass button.

<script type="text/javascript" language="Javascript"> 
    MasterPass.client.checkout({ 
       "requestPairing":true,                                                      //required
       "requestToken":"insert_checkout_request_token_here",                        //required
       "pairingRequestToken":"insert_pairing_request_token_here",                  //required
       "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",           //required
       "merchantCheckoutId":"insert_checkout_id_here",                             //required
       "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],      //required
       "allowedCardTypes":["master","amex","diners","discover","maestro","visa"],  //optional
       "version":"v6",                                                             //optional
       "successCallback": function(mpLightboxResponse){ ... },                     //optional
       "failureCallback": function(mpLightboxResponse){ ... },                     //optional
       "cancelCallback": function(mpLightboxResponse){ ... }                       //optional
    });
</script>

• requestPairing: To enable pairing, value must be true.
• requestToken: The checkout request token generated in Step 1.
• pairingRequestToken: The pairing request token generated in Step 1.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the merchant onboarding process.
• requestedDataTypes: The data types the merchant requests for pairing. PROFILE and CARD are required.
• allowedCardTypes: Card types accepted by the merchant (default is all card types).
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass Lightbox flow ends successfully.
• failureCallback: The function that will be called if the MasterPass Lightbox flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass Lightbox flow.

5. Redirect to callback URL or call callback function

After the consumer completes checkout, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will redirect to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

On success

On success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• checkout_resource_url: The API URL that will be used to retrieve checkout information in Step 7.
• oauth_verifier: The checkout verifier token that is used to retrieve the access token in Step 6.
• oauth_token: The checkout request token that is used to retrieve the access token in Step 6. This token has the same value as the checkout request token that is generated in Step 1.
• pairing_verifier: The pairing verifier token that is used to retrieve the long access token in Step 6.
• pairing_token: The pairing request token used to retrieve the long access token in Step 6.

Example Callback URL (Success)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F
10706241%3Fwallet%3Dphw
&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458
&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

Example Callback URL (Cancel)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

6. Call Access Token Service (2 times)

If the checkout was completed successfully, the next step is to make two Access Token Service calls. The first call uses the checkout request token and the checkout verifier token from Step 5 to retrieve a checkout access token. This checkout access token will be used in the next step to retrieve checkout data from the current transaction.

The second call uses the pairing request token and the pairing verifier token from Step 5 to retrieve a long access token. The long access token will be used to retrieve pre-checkout data for this consumer in future transactions.

AccessTokenResponse accessTokenResponse = AccessTokenApi.Create(request_token, verifier_token);
string accessToken = accessTokenResponse.OauthToken;

AccessTokenResponse accessTokenResponse = AccessTokenApi.Create(pairing_request_token, pairing_verifier_token);
string long_access_token = accessTokenResponse.OauthToken; // store for future requests

7. Retrieve payment, shipping data, rewards and 3DS details

Use the checkout resource URL received in Step 5 and the checkout access token from Step 6 to retrieve the consumer’s payment, shipping, reward and 3-D Secure information from MasterPass.

string checkoutId = checkoutResourceUrl.IndexOf('?') != -1 ? checkoutResourceUrl.Substring(checkoutResourceUrl.LastIndexOf('/') + 1).Split('?')[0] : checkoutResourceUrl.Substring(checkoutResourceUrl.LastIndexOf('/') + 1);

Checkout checkout = CheckoutApi.Show(checkoutId, accessToken);

Card card = checkout.Card;
Address billingAddress = card.BillingAddress;
Contact contact = checkout.Contact;
AuthenticationOptions authOptions = checkout.AuthenticationOptions;
string preCheckoutTransactionId = checkout.PreCheckoutTransactionId;
RewardProgram rewardProgram = checkout.RewardProgram;
ShippingAddress shippingAddress = checkout.ShippingAddress;
string transactionId = checkout.TransactionId;
string walletId = checkout.WalletID;

8. Process payment through a payment gateway

Using the data retrieved in Step 7, process the payment through the merchant's payment gateway.

9. Log transactions with MasterPass

After the payment has been processed in Step 8, make a service call to communicate the result of the transaction to MasterPass.

//Create an instance of MerchantTransactions
MerchantTransactions objMerchantTransactions = new MerchantTransactions();
List<MerchantTransaction> merchantTransactions = new List<MerchantTransaction>();
MerchantTransaction merchantTransaction = new MerchantTransaction
{
    TransactionId = "4549794", // from Step 7
    PurchaseDate = "2014-08-01T14:52:57.539-05:00",
    ExpressCheckoutIndicator = false,
    ApprovalCode = "888888",  // authorization code returned by payment gateway
    TransactionStatus = "Success",
    OrderAmount = 1229L, // total charged to card
    PreCheckoutTransactionId = "a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947",
    Currency = "USD",
    ConsumerKey = "0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d" //generated during onboarding process
};

merchantTransactions.Add(merchantTransaction);

objMerchantTransactions._MerchantTransactions = merchantTransactions;

//Call the PostbackService with required params
MerchantTransactions response = PostbackApi.Create(objMerchantTransactions);

Pairing without Checkout

1. Call Request Token Service

Call the Request Token Service to generate the pairing request token that will be used to invoke the MasterPass Lightbox. Pass a callback_url that the browser will redirect to when the Lightbox closes.

The Request Token Service must be called before the consumer clicks the Connect with MasterPass button.

string callback_url = "https://www.somemerchant.com/pairingcomplete.htm";
RequestTokenResponse requestTokenResponse = RequestTokenApi.Create(callback_url);
string pairing_request_token = requestTokenResponse.OauthToken;

2. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant site and MasterPass. The originUrl identifies the origin of the page that will initialize the Lightbox. This service requires the pairing request token from Step 1.

//Create an instance of MerchantInitializationRequest
MerchantInitializationRequest merchantInitializationRequest = new MerchantInitializationRequest
{
    OriginUrl = "https://somemerchant.com",
    OAuthToken = request_token
};

//Call the MerchantInitializationApi with required params
MerchantInitializationResponse merchantInitializationResponse = MerchantInitializationApi.Create(merchantInitializationRequest);

3. Invoke MasterPass UI (Lightbox) for pairing

Add the Connect with MasterPass button to the merchant site (for example, on the user account page) (see MasterPass Branding to customize size and locale).

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mp_connect_with_button_126px.png"/>

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment.

<!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

Invoke the MasterPass lightbox when the user clicks the Connect with MasterPass button.

<script type="text/javascript" language="Javascript"> 
    MasterPass.client.connect({ 
       "requestPairing":true,                                            //required
       "pairingRequestToken":"insert_pairing_request_token_here",        //required
       "callbackUrl":"http://www.somemerchant.com/pairingcomplete.htm", //required
       "merchantCheckoutId":"insert_checkout_id_here",                   //required
       "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],  //required
       "version":"v6"                                                    //optional
       "successCallback": function(mpLightboxResponse){ ... },           //optional
       "failureCallback": function(mpLightboxResponse){ ... },           //optional
       "cancelCallback": function(mpLightboxResponse){ ... }             //optional
    });
</script>

• requestPairing: To enable pairing, value must be true.
• pairingRequestToken: Your pairing request token generated in Step 1.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the Merchant Onboarding process.
• requestedDataTypes: The data types the merchant requests for pairing. PROFILE and CARD are required.
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass flow ends successfully.
• failureCallback: The function that will be called if the MasterPass flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass flow.

4. Redirect to callback URL or call callback function

After the lightbox closes, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will redirect to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

Example Callback URL (Success)

On Success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• pairing_verifier: The pairing verifier token that is used to retrieve the long access token in Step 6.
• pairing_token: The pairing request token used to retrieve the long access token in Step 6.

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=success
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

Example Callback URL (Cancel)

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=failure

Example Callback Function (Success)

function handleCallbackSuccess (data) {
    document.getElementById('pairingToken').value=data.pairing_token;
    document.getElementById('pairingVerifer').value=data.pairing_verifier;
}

5. Call Access Token Service

If the pairing was completed successfully, call the Access Token Service to retrieve a long access token. You will need the pairing request token and the pairing verifier token received in Step 4.

The long access token will be used to retrieve pre-checkout data for this consumer in the future. Store the long access token with this user's merchant account data so that it can be retrieved anytime the user logs into the merchant site.

AccessTokenResponse accessTokenResponse = AccessTokenApi.Create(pairing_request_token, pairing_verifier_token);
string long_access_token = accessTokenResponse.OauthToken; // store for future requests

Checkout after Pairing

1. Consumer logs onto merchant site

A consumer's long access token should have been stored with their account data for the merchant's site. When the consumer logs into their merchant site account, get their long access token.

2. Call PreCheckout Data Service

Use the consumer's long access token to retrieve pre-checkout data. The data types returned will be the types that were requested via the requestedDataTypes parameter when the Lightbox was invoked (Step 4 of Pairing During Checkout or Step 3 of Pairing Without Checkout).

string[] requestedDataTypes = { "REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD" };
PrecheckoutDataRequest preCheckoutDataRequest = new PrecheckoutDataRequest();
List<PairingDataType> lstPairingDataType = new List<PairingDataType>();
//foreach (var item in requestedDataTypes)
//{
//    lstPairingDataType.Add(new PairingDataType
//    {
//        Type = item
//    });
//}
lstPairingDataType = requestedDataTypes.Select(item => new PairingDataType() { Type = item }).ToList();

preCheckoutDataRequest.PairingDataTypes.PairingDataType = lstPairingDataType;

PrecheckoutDataResponse response = PrecheckoutDataApi.Create(long_access_token, preCheckoutDataRequest);

3. Consumer makes card/shipping address selection

Display the wallet data retrieved in Step 2 to the consumer, and prompt the consumer to select from it. Save the selected cardId, shippingId, and (if applicable) rewardId to be used on the Place Order page of the merchant site.

4. Call Request Token Service

Call the Request Token Service to generate the request token that will be used to invoke the MasterPass Lightbox. Pass a callback_url that the browser will redirect to when the Lightbox closes.

The Request Token Service must be called before creating the Buy with MasterPass button.

string callback_url = "https://www.somemerchant.com/checkoutconfirm.htm";
RequestTokenResponse requestTokenResponse = RequestTokenApi.Create(callback_url);
string request_token = requestTokenResponse.OauthToken;

5. Call Shopping Cart Service

The Shopping Cart Service enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. This service requires the request token from Step 4.

Each ShoppingCartItem must have a description, quantity, and value. Value is represented as an integer (for example, USD 100.00 is 10000), and is calculated as the cost of a single item multiplied by the quantity of that item. A ShoppingCartItem may also have an optional imageURL.

The Shopping Cart Service must be called before creating the Buy with MasterPass button.

//Create an instance of ShoppingCartRequest
ShoppingCartRequest shoppingCartRequest = new ShoppingCartRequest();
ShoppingCart shoppingCart = new ShoppingCart();
List<ShoppingCartItem> shoppingCartItems = new List<ShoppingCartItem>();
shoppingCartItems.Add(new ShoppingCartItem
{
    Value = 1900L,
    Description = "This is one item",
    Quantity = 1
});
shoppingCartItems.Add(new ShoppingCartItem
{
    ImageURL = "https://somemerchant.com/someimage",
    Value = 10000L,
    Description = "Five items",
    Quantity = 5
});

shoppingCart.Subtotal = 11900L;
shoppingCart.CurrencyCode = "USD";
shoppingCart.ShoppingCartItem = shoppingCartItems;

shoppingCartRequest.ShoppingCart = shoppingCart;
shoppingCartRequest.OAuthToken = request_token;

//Call the ShoppingCartService with required params
ShoppingCartResponse shoppingCartResponse = ShoppingCartApi.Create(shoppingCartRequest);

6. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant site and MasterPass. The originUrl identifies the origin of the page that will invoke the Lightbox. This service requires the request token from Step 4.

The Merchant Initialization Service must be called before creating the Buy with MasterPass button.

//Create an instance of MerchantInitializationRequest
MerchantInitializationRequest merchantInitializationRequest = new MerchantInitializationRequest
{
    OriginUrl = "https://somemerchant.com",
    OAuthToken = request_token
};

//Call the MerchantInitializationApi with required params
MerchantInitializationResponse merchantInitializationResponse = MerchantInitializationApi.Create(merchantInitializationRequest);

7. Create Buy With MasterPass Button

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment

 <!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

On the Place Order page of the merchant's website, create the Buy with MasterPass button using the cardId, addressId, and rewardId from Step 3 and the request token from Step 4.

<script type="text/javascript" language="Javascript">
MasterPass.client.checkout({
     "requestToken":"insert_request_token_here",                       //required
     "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm", //required
     "merchantCheckoutId":"insert_checkout_id_here",                   //required
     "cardId":"insert_selected_card_id_here",                          //required
     "shippingId":"insert_selected_shipping_address_id_here",          //required
     "precheckoutTransactionId":"insert_prechechout_txn_id_here",      //required
     "walletName":"insert_wallet_name_here",                           //required
     "consumerWalletId":"insert_consumer_walletid_here",               //required
     "loyaltyId":"insert_loyalty_id_here",                             //optional
     "requireShippingDestination": "true"                              //optional                                                                                                                                                                 
     "version":"v6",                                                   //optional
     "successCallback": function(mpLightboxResponse){ ... },           //optional
     "failureCallback": function(mpLightboxResponse){ ... },           //optional
     "cancelCallback": function(mpLightboxResponse){ ... }             //optional
});
</script>

• requestToken: The request token generated in Step 4.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the Merchant Onboarding process.
• cardId: The identifier of the selected card collected in Step 3.
• shippingId: The identifier of the shipping information collected in Step 3.
• precheckoutTransactionId: The pre-checkout transaction identifier collected in Step 3.
• walletName: The consumer's wallet name collected in Step 3.
• consumerWalletId: The consumer's wallet identifier collected in Step 3.
• loyaltyId: The rewardId, optionally collected in Step 3.
• requireShippingDestination: Denotes whether the consumer's shipping information is required.
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass flow ends successfully.
• failureCallback: The function that will be called if the MasterPass flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass flow.

8. Redirect to callback URL or call callback function

After the consumer completes checkout, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will redirected to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

on Success

On Success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• checkout_resource_url: The API URL that will be used to retrieve checkout information in Step 10.
• oauth_verifier: The verifier token that is used in conjunction with the request token to retrieve the access token in Step 9.
• oauth_token: The request token that is used in conjunction with the verifier token to retrieve the access token in Step 9. This token has the same value as the request token that is generated in Step 1.

Example Callback URL (Success)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass\%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw
&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13
&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc

Example Callback URL (Cancel)

http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=failure

Example Callback Function (Success)

function handleCallbackSuccess (data) {
    callYourServerWith(data.oauth_token, data.oauth_verifier, data.checkout_resource_url);
}

9. Call Access Token Service

If the checkout was completed successfully, call the Access Token Service to retrieve an access token. You will need the request token and the verifier token received in Step 8.

As there is no need to retrieve a long access token again, only this one call to the Access Token Service will be made.

AccessTokenResponse accessTokenResponse = AccessTokenApi.Create(request_token, verifier_token);
string accessToken = accessTokenResponse.OauthToken;

10. Retrieve Payment, Shipping Data, Rewards and 3-D Secure Details

Use the Checkout Resource URL received in Step 8 and the access token from Step 9 to retrieve the constomer’s payment, shipping, reward and 3-D Secure information from MasterPass.

string checkoutId = checkoutResourceUrl.IndexOf('?') != -1 ? checkoutResourceUrl.Substring(checkoutResourceUrl.LastIndexOf('/') + 1).Split('?')[0] : checkoutResourceUrl.Substring(checkoutResourceUrl.LastIndexOf('/') + 1);

Checkout checkout = CheckoutApi.Show(checkoutId, accessToken);

Card card = checkout.Card;
Address billingAddress = card.BillingAddress;
Contact contact = checkout.Contact;
AuthenticationOptions authOptions = checkout.AuthenticationOptions;
string preCheckoutTransactionId = checkout.PreCheckoutTransactionId;
RewardProgram rewardProgram = checkout.RewardProgram;
ShippingAddress shippingAddress = checkout.ShippingAddress;
string transactionId = checkout.TransactionId;
string walletId = checkout.WalletID;

11. Process Payment through a payment gateway

Using the data retrieved in Step 10, process the payment through the merchant's payment gateway.

12. Log Transactions with MasterPass

After the payment has been processed in Step 11, make a service call to communicate the result of the transaction to MasterPass.

//Create an instance of MerchantTransactions
MerchantTransactions objMerchantTransactions = new MerchantTransactions();
List<MerchantTransaction> merchantTransactions = new List<MerchantTransaction>();
MerchantTransaction merchantTransaction = new MerchantTransaction
{
    TransactionId = "4549794", // from Step 7
    PurchaseDate = "2014-08-01T14:52:57.539-05:00",
    ExpressCheckoutIndicator = false,
    ApprovalCode = "888888",  // authorization code returned by payment gateway
    TransactionStatus = "Success",
    OrderAmount = 1229L, // total charged to card
    PreCheckoutTransactionId = "a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947",
    Currency = "USD",
    ConsumerKey = "0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d" //generated during onboarding process
};

merchantTransactions.Add(merchantTransaction);

objMerchantTransactions._MerchantTransactions = merchantTransactions;

//Call the PostbackService with required params
MerchantTransactions response = PostbackApi.Create(objMerchantTransactions);

Connected Checkout Integration

Pairing During Checkout

1. Call Request Token Service (2 times)

Call the Request Token Service twice. The first call generates a pairing request token, which will be used to gain the long access token needed to pair the consumer's wallet and merchant account.

The second call generates a checkout request token that will be used to invoke the MasterPass Lightbox. Pass a callback_url that the browser will redirect to when the Lightbox closes.

The Request Token Service calls must be made before the consumer clicks the Buy with MasterPass button.

callback_url = "https://www.somemerchant.com/checkoutconfirm.htm"
pairing_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
pairing_request_token = pairing_token_response.oauth_token;

request_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
request_token = request_token_response.oauth_token;

2. Call Shopping Cart Service

The Shopping Cart Service enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. This service requires the checkout request token from Step 1.

Each shopping_cart_item must have a description, quantity, and value. Value is represented as an integer (for example, USD 100.00 is 10000), and is calculated as the cost of a single item multiplied by the quantity of that item. A shopping_cart_item may also have an optional image_url.

The Shopping Cart Service must be called before the consumer clicks the Buy with MasterPass button.

shopping_cart_request = MastercardMasterpassMerchant::ShoppingCartRequest.new(
    :o_auth_token => request_token,
    :shopping_cart => MastercardMasterpassMerchant::ShoppingCart.new(
        :currency_code => 'USD',
        :subtotal => '11900',
        :shopping_cart_item => [
            MastercardMasterpassMerchant::ShoppingCartItem.new(
                :description => 'One Item',
                :quantity => 1,
                :value => 1900
            ),
            MastercardMasterpassMerchant::ShoppingCartItem.new(
                :description => 'Five of an Item',
                :quantity => 5,
                :value => 10000,
                :image_url => 'http://somemerchant.com/someimage'
            )
        ]
    )
)

shopping_cart_response = MastercardMasterpassMerchant::Api::ShoppingCartApi.create(shopping_cart_request)

3. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant and MasterPass. The originUrl identifies the origin of the page that will initialize the Lightbox. This service requires the checkout request token from Step 1.

The Merchant Initialization Service must be called before the consumer clicks the Buy with MasterPass button.

merchant_init_request = MastercardMasterpassMerchant::MerchantInitializationRequest.new(
    :o_auth_token => request_token,
    :origin_url => 'https://somemerchant.com'
)

merchant_init_response = MastercardMasterpassMerchant::Api::MerchantInitializationApi.create(merchant_init_request)

4. Invoke MasterPass UI (Lightbox) for checkout

On the Checkout Page of the merchant's website, add the Buy with MasterPass button to your HTML (see MasterPass Branding to customize size and locale).

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png"/>

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment.

<!-- url to jquery 1.10.2 -->
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
  <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
  <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

Invoke the MasterPass lightbox when the user clicks the Buy with MasterPass button.

<script type="text/javascript" language="Javascript"> 
    MasterPass.client.checkout({ 
       "requestPairing":true,                                                      //required
       "requestToken":"insert_checkout_request_token_here",                        //required
       "pairingRequestToken":"insert_pairing_request_token_here",                  //required
       "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",           //required
       "merchantCheckoutId":"insert_checkout_id_here",                             //required
       "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],      //required
       "allowedCardTypes":["master","amex","diners","discover","maestro","visa"],  //optional
       "version":"v6",                                                             //optional
       "successCallback": function(mpLightboxResponse){ ... },                     //optional
       "failureCallback": function(mpLightboxResponse){ ... },                     //optional
       "cancelCallback": function(mpLightboxResponse){ ... }                       //optional
    });
</script>

• requestPairing: To enable pairing, value must be true.
• requestToken: The checkout request token generated in Step 1.
• pairingRequestToken: The pairing request token generated in Step 1.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the merchant onboarding process.
• requestedDataTypes: The data types the merchant requests for pairing. PROFILE and CARD are required.
• allowedCardTypes: Card types accepted by the merchant (default is all card types).
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass Lightbox flow ends successfully.
• failureCallback: The function that will be called if the MasterPass Lightbox flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass Lightbox flow.

5. Redirect to callback URL or call callback function

After the consumer completes checkout, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will redirect to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

On success

On success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• checkout_resource_url: The API URL that will be used to retrieve checkout information in Step 7.
• oauth_verifier: The checkout verifier token that is used to retrieve the access token in Step 6.
• oauth_token: The checkout request token that is used to retrieve the access token in Step 6. This token has the same value as the checkout request token that is generated in Step 1.
• pairing_verifier: The pairing verifier token that is used to retrieve the long access token in Step 6.
• pairing_token: The pairing request token used to retrieve the long access token in Step 6.

Example Callback URL (Success)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F
10706241%3Fwallet%3Dphw
&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458
&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

Example Callback URL (Cancel)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

6. Call Access Token Service (2 times)

If the checkout was completed successfully, the next step is to make two Access Token Service calls. The first call uses the checkout request token and the checkout verifier token from Step 5 to retrieve a checkout access token. This checkout access token will be used in the next step to retrieve checkout data from the current transaction.

The second call uses the pairing request token and the pairing verifier token from Step 5 to retrieve a long access token. The long access token will be used to retrieve pre-checkout data for this consumer in future transactions.

access_token_response = MastercardCoreSdk::Api::AccessTokenApi.create(verifier_token, request_token)
access_token = access_token_response.oauth_token

long_access_token_response = MastercardCoreSdk::Api::AccessTokenApi.create(pairing_verifier_token, pairing_request_token)
long_access_token = long_access_token_response.oauth_token

7. Retrieve payment, shipping data, rewards and 3DS details

Use the checkout resource URL received in Step 5 and the checkout access token from Step 6 to retrieve the consumer’s payment, shipping, reward and 3-D Secure information from MasterPass.

start_index = checkout_resource_url.rindex('/') + 1
end_index = checkout_resource_url.index('?').nil? ? -1 : checkout_resource_url.index('?')
path_id = checkout_resource_url[start_index..end_index]

checkout = MastercardMasterpassMerchant::Api::CheckoutApi.show(path_id, access_token)
card = checkout.card
billing_address = card.billing_address
contact = checkout.contact
auth_options = checkout.authentication_options
precheckout_transaction_id = checkout.pre_checkout_transaction_id
reward_program = checkout.reward_program
shipping_address = checkout.shipping_address
transaction_id = checkout.transaction_id
wallet_id = checkout.wallet_id

8. Process payment through a payment gateway

Using the data retrieved in Step 7, process the payment through the merchant's payment gateway.

9. Log transactions with MasterPass

After the payment has been processed in Step 8, make a service call to communicate the result of the transaction to MasterPass.

merchant_transactions = MastercardMasterpassMerchant::MerchantTransactions.new(
    :merchant_transactions => [
        MastercardMasterpassMerchant::MerchantTransaction.new(
            :transaction_id => 4549794,
            :consumer_key => '0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d',
            :currency => 'USD',
            :order_amount => 1800,
            :transaction_status => 'Success',
            :approval_code => '888888',
            :pre_checkout_transaction_id => 'a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947',
            :express_checkout_indicator => false,
            :purchase_date => '2016-06-23T15:09:32+00:00'
        )
    ]
)

merchant_trans_response = MastercardMasterpassMerchant::Api::PostbackApi.create(merchant_transactions)

Pairing without Checkout

1. Call Request Token Service

Call the Request Token Service to generate the pairing request token that will be used to invoke the MasterPass Lightbox. Pass a callback_url that the browser will redirect to when the Lightbox closes.

The Request Token Service must be called before the consumer clicks the Connect with MasterPass button.

callback_url = "https://www.somemerchant.com/checkoutconfirm.htm"
pairing_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
pairing_request_token = pairing_token_response.oauth_token;

2. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant site and MasterPass. The origin_url identifies the origin of the page that will initialize the Lightbox. This service requires the pairing request token from Step 1.

merchant_init_request = MastercardMasterpassMerchant::MerchantInitializationRequest.new(
    :o_auth_token => pairing_request_token,
    :origin_url => 'https://somemerchant.com'
)

merchant_init_response = MastercardMasterpassMerchant::Api::MerchantInitializationApi.create(merchant_init_request)

3. Invoke MasterPass UI (Lightbox) for pairing

Add the Connect with MasterPass button to the merchant site (for example, on the user account page) (see MasterPass Branding to customize size and locale).

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mp_connect_with_button_126px.png"/>

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment.

<!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

Invoke the MasterPass lightbox when the user clicks the Connect with MasterPass button.

<script type="text/javascript" language="Javascript"> 
    MasterPass.client.connect({ 
       "requestPairing":true,                                            //required
       "pairingRequestToken":"insert_pairing_request_token_here",        //required
       "callbackUrl":"http://www.somemerchant.com/pairingcomplete.htm", //required
       "merchantCheckoutId":"insert_checkout_id_here",                   //required
       "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],  //required
       "version":"v6"                                                    //optional
       "successCallback": function(mpLightboxResponse){ ... },           //optional
       "failureCallback": function(mpLightboxResponse){ ... },           //optional
       "cancelCallback": function(mpLightboxResponse){ ... }             //optional
    });
</script>

• requestPairing: To enable pairing, value must be true.
• pairingRequestToken: Your pairing request token generated in Step 1.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the Merchant Onboarding process.
• requestedDataTypes: The data types the merchant requests for pairing. PROFILE and CARD are required.
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass flow ends successfully.
• failureCallback: The function that will be called if the MasterPass flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass flow.

4. Redirect to callback URL or call callback function

After the lightbox closes, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will redirect to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

Example Callback URL (Success)

On Success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• pairing_verifier: The pairing verifier token that is used to retrieve the long access token in Step 6.
• pairing_token: The pairing request token used to retrieve the long access token in Step 6.

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=success
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

Example Callback URL (Cancel)

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=failure

Example Callback Function (Success)

function handleCallbackSuccess (data) {
    document.getElementById('pairingToken').value=data.pairing_token;
    document.getElementById('pairingVerifer').value=data.pairing_verifier;
}

5. Call Access Token Service

If the pairing was completed successfully, call the Access Token Service to retrieve a long access token. You will need the pairing request token and the pairing verifier token received in Step 4.

The long access token will be used to retrieve pre-checkout data for this consumer in the future. Store the long access token with this user's merchant account data so that it can be retrieved anytime the user logs into the merchant site.

long_access_token_response = MastercardCoreSdk::Api::AccessTokenApi.create(pairing_verifier_token, pairing_request_token)
long_access_token = long_access_token_response.oauth_token

Checkout after Pairing

1. Consumer logs onto merchant site

A consumer's long access token should have been stored with their account data for the merchant's site. When the consumer logs into their merchant site account, get their long access token.

2. Call PreCheckout Data Service

Use the consumer's long access token to retrieve pre-checkout data. The data types returned will be the types that were requested via the requestedDataTypes parameter when the Lightbox was invoked (Step 4 of Pairing During Checkout or Step 3 of Pairing Without Checkout).

requested_data_types = ['REWARD_PROGRAM', 'ADDRESS', 'PROFILE', 'CARD']
pairing_data_types = []
requested_data_types.each do |data_type|
  pairing_data_type = MastercardMasterpassMerchant::PairingDataType.new
  pairing_data_type.type = data_type
  pairing_data_types.append(pairing_data_type)
end

pre_checkout_data_request = MastercardMasterpassMerchant::PrecheckoutDataRequest.new(
    :pairing_data_types => MastercardMasterpassMerchant::PairingDataTypes.new(
        :pairing_data_type => pairing_data_types
    )
)

response = MastercardMasterpassMerchant::Api::PrecheckoutDataApi.create(long_access_token, pre_checkout_data_request)

3. Consumer makes card/shipping address selection

Display the wallet data retrieved in Step 2 to the consumer, and prompt the consumer to select from it. Save the selected cardId, shippingId, and (if applicable) rewardId to be used on the Place Order page of the merchant site.

4. Call Request Token Service

Call the Request Token Service to generate the request token that will be used to invoke the MasterPass Lightbox. Pass a callback_url that the browser will redirect to when the Lightbox closes.

The Request Token Service must be called before creating the Buy with MasterPass button.

callback_url = "https://www.somemerchant.com/checkoutconfirm.htm"
request_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
request_token = request_token_response.oauth_token;

5. Call Shopping Cart Service

The Shopping Cart Service enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. This service requires the request token from Step 4.

Each shopping_cart_item must have a description, quantity, and value. Value is represented as an integer (for example, USD 100.00 is 10000), and is calculated as the cost of a single item multiplied by the quantity of that item. A shopping_cart_item may also have an optional image_url.

The Shopping Cart Service must be called before creating the Buy with MasterPass button.

shopping_cart_request = MastercardMasterpassMerchant::ShoppingCartRequest.new(
    :o_auth_token => request_token,
    :shopping_cart => MastercardMasterpassMerchant::ShoppingCart.new(
        :currency_code => 'USD',
        :subtotal => '11900',
        :shopping_cart_item => [
            MastercardMasterpassMerchant::ShoppingCartItem.new(
                :description => 'One Item',
                :quantity => 1,
                :value => 1900
            ),
            MastercardMasterpassMerchant::ShoppingCartItem.new(
                :description => 'Five of an Item',
                :quantity => 5,
                :value => 10000,
                :image_url => 'http://somemerchant.com/someimage'
            )
        ]
    )
)

shopping_cart_response = MastercardMasterpassMerchant::Api::ShoppingCartApi.create(shopping_cart_request)

6. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant site and MasterPass. The originUrl identifies the origin of the page that will invoke the Lightbox. This service requires the request token from Step 4.

The Merchant Initialization Service must be called before creating the Buy with MasterPass button.

merchant_init_request = MastercardMasterpassMerchant::MerchantInitializationRequest.new(
    :o_auth_token => request_token,
    :origin_url => 'https://somemerchant.com'
)

merchant_init_response = MastercardMasterpassMerchant::Api::MerchantInitializationApi.create(merchant_init_request)

7. Create Buy With MasterPass Button

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment

 <!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

On the Place Order page of the merchant's website, create the Buy with MasterPass button using the cardId, addressId, and rewardId from Step 3 and the request token from Step 4.

<script type="text/javascript" language="Javascript">
MasterPass.client.checkout({
     "requestToken":"insert_request_token_here",                       //required
     "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm", //required
     "merchantCheckoutId":"insert_checkout_id_here",                   //required
     "cardId":"insert_selected_card_id_here",                          //required
     "shippingId":"insert_selected_shipping_address_id_here",          //required
     "precheckoutTransactionId":"insert_prechechout_txn_id_here",      //required
     "walletName":"insert_wallet_name_here",                           //required
     "consumerWalletId":"insert_consumer_walletid_here",               //required
     "loyaltyId":"insert_loyalty_id_here",                             //optional
     "requireShippingDestination": "true"                              //optional                                                                                                                                                                 
     "version":"v6",                                                   //optional
     "successCallback": function(mpLightboxResponse){ ... },           //optional
     "failureCallback": function(mpLightboxResponse){ ... },           //optional
     "cancelCallback": function(mpLightboxResponse){ ... }             //optional
});
</script>

• requestToken: The request token generated in Step 4.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the Merchant Onboarding process.
• cardId: The identifier of the selected card collected in Step 3.
• shippingId: The identifier of the shipping information collected in Step 3.
• precheckoutTransactionId: The pre-checkout transaction identifier collected in Step 3.
• walletName: The consumer's wallet name collected in Step 3.
• consumerWalletId: The consumer's wallet identifier collected in Step 3.
• loyaltyId: The rewardId, optionally collected in Step 3.
• requireShippingDestination: Denotes whether the consumer's shipping information is required.
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass flow ends successfully.
• failureCallback: The function that will be called if the MasterPass flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass flow.

8. Redirect to callback URL or call callback function

After the consumer completes checkout, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will redirected to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

On Success

On Success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• checkout_resource_url: The API URL that will be used to retrieve checkout information in Step 10.
• oauth_verifier: The verifier token that is used in conjunction with the request token to retrieve the access token in Step 9.
• oauth_token: The request token that is used in conjunction with the verifier token to retrieve the access token in Step 9. This token has the same value as the request token that is generated in Step 1.

Example Callback URL (Success)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass\%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw
&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13
&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc

Example Callback URL (Cancel)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

Example Callback Function (Success)

function handleCallbackSuccess (data) {
    callYourServerWith(data.oauth_token, data.oauth_verifier, data.checkout_resource_url);
}

9. Call Access Token Service

If the checkout was completed successfully, call the Access Token Service to retrieve an access token. You will need the request token and the verifier token received in Step 8.

As there is no need to retrieve a long access token again, only this one call to the Access Token Service will be made.

access_token_response = MastercardCoreSdk::Api::AccessTokenApi.create(verifier_token, request_token)
access_token = access_token_response.oauth_token

10. Retrieve Payment, Shipping Data, Rewards and 3-D Secure Details

Use the Checkout Resource URL received in Step 8 and the access token from Step 9 to retrieve the constomer’s payment, shipping, reward and 3-D Secure information from MasterPass.

start_index = checkout_resource_url.rindex('/') + 1
end_index = checkout_resource_url.index('?').nil? ? -1 : checkout_resource_url.index('?')
path_id = checkout_resource_url[start_index..end_index]

checkout = MastercardMasterpassMerchant::Api::CheckoutApi.show(path_id, access_token)
card = checkout.card
billing_address = card.billing_address
contact = checkout.contact
auth_options = checkout.authentication_options
precheckout_transaction_id = checkout.pre_checkout_transaction_id
reward_program = checkout.reward_program
shipping_address = checkout.shipping_address
transaction_id = checkout.transaction_id
wallet_id = checkout.wallet_id

11. Process Payment through a payment gateway

Using the data retrieved in Step 10, process the payment through the merchant's payment gateway.

12. Log Transactions with MasterPass

After the payment has been processed in Step 11, make a service call to communicate the result of the transaction to MasterPass.

merchant_transactions = MastercardMasterpassMerchant::MerchantTransactions.new(
    :merchant_transactions => [
        MastercardMasterpassMerchant::MerchantTransaction.new(
            :transaction_id => 4549794,
            :consumer_key => '0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d',
            :currency => 'USD',
            :order_amount => 1800,
            :transaction_status => 'Success',
            :approval_code => '888888',
            :pre_checkout_transaction_id => 'a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947',
            :express_checkout_indicator => false,
            :purchase_date => '2016-06-23T15:09:32+00:00'
        )
    ]
)

merchant_trans_response = MastercardMasterpassMerchant::Api::PostbackApi.create(merchant_transactions)

Connected Checkout Integration

Pairing During Checkout

1. Call Request Token Service (2 times)

Call the Request Token Service twice. The first call generates a pairing request token, which will be used to gain the long access token needed to pair the consumer's wallet and merchant account.

The second call generates a checkout request token that will be used to invoke the MasterPass Lightbox. Pass a callbackUrl that the browser will redirect to when the Lightbox closes.

The Request Token Service calls must be made before the consumer clicks the Buy with MasterPass button.

$callbackUrl = "https://www.somemerchant.com/checkoutconfirm.htm";

$pairingResponse = RequestTokenApi::create($callbackUrl);
$pairingRequestToken = $pairingResponse->getOauthToken();

$checkoutResponse = RequestTokenApi::create($callbackUrl);
$checkoutRequestToken = $checkoutResponse::getOauthToken();

2. Call Shopping Cart Service

The Shopping Cart Service enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. This service requires the checkout request token from Step 1.

Each ShoppingCartItem must have a description, quantity, and value. Value is represented as an integer (for example, USD 100.00 is 10000), and is calculated as the cost of a single item multiplied by the quantity of that item. A ShoppingCartItem may also have an optional ImageURL.

The Shopping Cart Service must be called before the consumer clicks the Buy with MasterPass button.

//Build Out ShoppingCartRequest object
$shoppingCartItem1 = new ShoppingCartItem(
	array(
		"Value" => 700,
		"Description" => "This is one item",
		"Quantity" => 1,
		"ImageURL" => "https://somemerchant.com/someimage"
	)
);

$shoppingCartItem2 = new ShoppingCartItem(
	array(
		"Value" => 300,
		"Description" => "This is another item",
		"Quantity" => 1,
		"ImageURL" => "https://somemerchant.com/someotherimage"
	)
);

$shoppingCart = new ShoppingCart(
	array(
		"CurrencyCode" => "USD",
		"Subtotal" => 1000,
		"ShoppingCartItem" => array($shoppingCartItem1, $shoppingCartItem2)
	)
);

$shoppingCartRequest = new ShoppingCartRequest(
	array(
		"OAuthToken" => $requestToken,
		"OriginUrl" => $callbackDomain,
		"ShoppingCart" => $shoppingCart,
	)
);

//Call the ShoppingCartService with required params
$shoppingCartResponse = ShoppingCartApi::create($shoppingCartRequest);

3. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant and MasterPass. The OriginUrl identifies the origin of the page that will initialize the Lightbox. This service requires the checkout request token from Step 1.

The Merchant Initialization Service must be called before the consumer clicks the Buy with MasterPass button.

//Create an instance of MerchantInitializationRequest
$merchantInitializationRequest = new MerchantInitializationRequest(
	array(
		"OriginUrl" => "https://somemerchant.com",
		"OAuthToken" => $checkoutRequestToken
	)
);

//Call the MerchantInitializationApi with required params
$merchantInitializationResponse = MerchantInitializationApi::create($merchantInitializationRequest);

4. Invoke MasterPass UI (Lightbox) for checkout

On the Checkout Page of the merchant's website, add the Buy with MasterPass button to your HTML (see MasterPass Branding to customize size and locale).

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png"/>

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment.

<!-- url to jquery 1.10.2 -->
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
  <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
  <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

Invoke the MasterPass lightbox when the user clicks the Buy with MasterPass button.

<script type="text/javascript" language="Javascript"> 
    MasterPass.client.checkout({ 
       "requestPairing":true,                                                      //required
       "requestToken":"insert_checkout_request_token_here",                        //required
       "pairingRequestToken":"insert_pairing_request_token_here",                  //required
       "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",           //required
       "merchantCheckoutId":"insert_checkout_id_here",                             //required
       "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],      //required
       "allowedCardTypes":["master","amex","diners","discover","maestro","visa"],  //optional
       "version":"v6",                                                             //optional
       "successCallback": function(mpLightboxResponse){ ... },                     //optional
       "failureCallback": function(mpLightboxResponse){ ... },                     //optional
       "cancelCallback": function(mpLightboxResponse){ ... }                       //optional
    });
</script>

• requestPairing: To enable pairing, value must be true.
• requestToken: The checkout request token generated in Step 1.
• pairingRequestToken: The pairing request token generated in Step 1.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the merchant onboarding process.
• requestedDataTypes: The data types the merchant requests for pairing. PROFILE and CARD are required.
• allowedCardTypes: Card types accepted by the merchant (default is all card types).
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass Lightbox flow ends successfully.
• failureCallback: The function that will be called if the MasterPass Lightbox flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass Lightbox flow.

5. Redirect to callback URL or call callback function

After the consumer completes checkout, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will redirect to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

On success

On success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• checkout_resource_url: The API URL that will be used to retrieve checkout information in Step 7.
• oauth_verifier: The checkout verifier token that is used to retrieve the access token in Step 6.
• oauth_token: The checkout request token that is used to retrieve the access token in Step 6. This token has the same value as the checkout request token that is generated in Step 1.
• pairing_verifier: The pairing verifier token that is used to retrieve the long access token in Step 6.
• pairing_token: The pairing request token used to retrieve the long access token in Step 6.

Example Callback URL (Success)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F
10706241%3Fwallet%3Dphw
&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458
&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

Example Callback URL (Cancel)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

6. Call Access Token Service (2 times)

If the checkout was completed successfully, the next step is to make two Access Token Service calls. The first call uses the checkout request token and the checkout verifier token from Step 5 to retrieve a checkout access token. This checkout access token will be used in the next step to retrieve checkout data from the current transaction.

The second call uses the pairing request token and the pairing verifier token from Step 5 to retrieve a long access token. The long access token will be used to retrieve pre-checkout data for this consumer in future transactions.

$checkoutAccessTokenResponse = AccessTokenApi::create(oauthCheckoutRequestToken, oauthCheckoutVerifierToken);
$checkoutAccessToken = checkoutAccessTokenResponse->getOauthToken();

$longAccessTokenResponse = AccessTokenApi::create(oauthPairingRequestToken, oauthPairingVerifierToken);
$longAccessToken = longAccessTokenResponse->getOauthToken(); // store for future requests

7. Retrieve payment, shipping data, rewards and 3DS details

Use the checkout resource URL received in Step 5 and the checkout access token from Step 6 to retrieve the consumer’s payment, shipping, reward and 3-D Secure information from MasterPass.

$explodedURL = explode("/", $checkoutResourceUrl);
$checkoutId = array_pop($explodedURL);
if(strpos($checkoutId, "?") !== false){
	$checkoutId = explode($checkoutId, "?")[0];
}

$logger->info($checkoutId);

$checkout = CheckoutApi::show($checkoutId, $accessToken);

$card = $checkout->getCard();
$billingAddress = $card->getBillingAddress();
$contact = $checkout->getContact();
$authOptions = checkout->getAuthenticationOptions(); 
$preCheckoutTransactionId = checkout->getPreCheckoutTransactionId(); 
$rewardProgram = checkout->getRewardProgram(); 
$shippingAddress = checkout->getShippingAddress();
$transactionId = checkout->getTransactionId();
$walletId = checkout->getWalletID();

8. Process payment through a payment gateway

Using the data retrieved in Step 7, process the payment through the merchant's payment gateway.

9. Log transactions with MasterPass

After the payment has been processed in Step 8, make a service call to communicate the result of the transaction to MasterPass.

//Create an instance of MerchantTransactions
$merchantTransaction = new MerchantTransaction(
	array(
		"TransactionId" => "4549794",
		"ConsumerKey" => "0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d", //generated during onboarding process
		"Currency" => "USD",
		"OrderAmount" => 500, // total charged to card
		"TransactionStatus" => "Success",
		"ApprovalCode" => "888888", // authorization code returned by payment gateway
		"PrecheckoutTransactionId" => "a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947",
		"ExpressCheckoutIndicator" => false,
		"PurchaseDate" => date("Y/m/d H:i:s")
	)
);
$request = new MerchantTransactions(array("MerchantTransactions" => array($merchantTransaction)));

//Call the PostbackService with required params
$response = PostbackApi::create($request);

Pairing without Checkout

1. Call Request Token Service

Call the Request Token Service to generate the pairing request token that will be used to invoke the MasterPass Lightbox. Pass a callbackUrl that the browser will redirect to when the Lightbox closes.

The Request Token Service must be called before the consumer clicks the Connect with MasterPass button.

$callbackUrl = "https://www.somemerchant.com/pairingcomplete.htm";
$requestTokenResponse = RequestTokenApi::create($callbackUrl);
$pairingRequestToken = $requestTokenResponse->getOauthToken();

2. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant site and MasterPass. The OriginUrl identifies the origin of the page that will initialize the Lightbox. This service requires the pairing request token from Step 1.

//Create an instance of MerchantInitializationRequest
$merchantInitializationRequest = new MerchantInitializationRequest(
	array(
		"OriginUrl" => "https://somemerchant.com",
		"OAuthToken" => $pairingRequestToken
	)
);

//Call the MerchantInitializationApi with required params
$merchantInitializationResponse = MerchantInitializationApi::create($merchantInitializationRequest);

3. Invoke MasterPass UI (Lightbox) for pairing

Add the Connect with MasterPass button to the merchant site (for example, on the user account page) (see MasterPass Branding to customize size and locale).

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mp_connect_with_button_126px.png"/>

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment.

<!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

Invoke the MasterPass lightbox when the user clicks the Connect with MasterPass button.

<script type="text/javascript" language="Javascript"> 
    MasterPass.client.connect({ 
       "requestPairing":true,                                            //required
       "pairingRequestToken":"insert_pairing_request_token_here",        //required
       "callbackUrl":"http://www.somemerchant.com/pairingcomplete.htm", //required
       "merchantCheckoutId":"insert_checkout_id_here",                   //required
       "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],  //required
       "version":"v6"                                                    //optional
       "successCallback": function(mpLightboxResponse){ ... },           //optional
       "failureCallback": function(mpLightboxResponse){ ... },           //optional
       "cancelCallback": function(mpLightboxResponse){ ... }             //optional
    });
</script>

• requestPairing: To enable pairing, value must be true.
• pairingRequestToken: Your pairing request token generated in Step 1.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the Merchant Onboarding process.
• requestedDataTypes: The data types the merchant requests for pairing. PROFILE and CARD are required.
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass flow ends successfully.
• failureCallback: The function that will be called if the MasterPass flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass flow.

4. Redirect to callback URL or call callback function

After the lightbox closes, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will redirect to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

Example Callback URL (Success)

On Success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• pairing_verifier: The pairing verifier token that is used to retrieve the long access token in Step 6.
• pairing_token: The pairing request token used to retrieve the long access token in Step 6.

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=success
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

Example Callback URL (Cancel)

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=failure

Example Callback Function (Success)

function handleCallbackSuccess (data) {
    document.getElementById('pairingToken').value=data.pairing_token;
    document.getElementById('pairingVerifer').value=data.pairing_verifier;
}

5. Call Access Token Service

If the pairing was completed successfully, call the Access Token Service to retrieve a long access token. You will need the pairing request token and the pairing verifier token received in Step 4.

The long access token will be used to retrieve pre-checkout data for this consumer in the future. Store the long access token with this user's merchant account data so that it can be retrieved anytime the user logs into the merchant site.

$accessTokenResponse = AccessTokenApi::create($pairingRequestToken, $pairingVerifierToken);
$longAccessToken = $accessTokenResponse->getOauthToken(); // store for future requests

Checkout after Pairing

1. Consumer logs onto merchant site

A consumer's long access token should have been stored with their account data for the merchant's site. When the consumer logs into their merchant site account, get their long access token.

2. Call PreCheckout Data Service

Use the consumer's long access token to retrieve pre-checkout data. The data types returned will be the types that were requested via the requestedDataTypes parameter when the Lightbox was invoked (Step 4 of Pairing During Checkout or Step 3 of Pairing Without Checkout).

$requestedDataTypes = array("REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD");

$preCheckoutDataRequest = new PreCheckoutDataRequest();
$pairingDataTypes = new PairingDataTypes();

foreach ($requestedDataTypes as $pairingType){
	$newPairingType = new PairingDataType(
		array(
			"Type" => $pairingType
		)
	);
	$pairingDataTypes->setPairingDataType = $newPairingType;
}

$preCheckoutDataRequest->setPairingDataTypes($pairingDataTypes);

$preCheckoutDataResponse = PrecheckoutDataApi::create($longAccessToken, $preCheckoutDataRequest);

3. Consumer makes card/shipping address selection

Display the wallet data retrieved in Step 2 to the consumer, and prompt the consumer to select from it. Save the selected cardId, shippingId, and (if applicable) rewardId to be used on the Place Order page of the merchant site.

4. Call Request Token Service

Call the Request Token Service to generate the request token that will be used to invoke the MasterPass Lightbox. Pass a callbackUrl that the browser will redirect to when the Lightbox closes.

The Request Token Service must be called before creating the Buy with MasterPass button.

$callbackUrl = "https://www.somemerchant.com/checkoutconfirm.htm";
$requestTokenResponse = RequestTokenApi::create($callbackUrl);
$requestToken = $requestTokenResponse->getOauthToken();

5. Call Shopping Cart Service

The Shopping Cart Service enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. This service requires the request token from Step 4.

Each ShoppingCartItem must have a description, quantity, and value. Value is represented as an integer (for example, USD 100.00 is 10000), and is calculated as the cost of a single item multiplied by the quantity of that item. A ShoppingCartItem may also have an optional ImageURL.

The Shopping Cart Service must be called before creating the Buy with MasterPass button.

//Build Out ShoppingCartRequest object
$shoppingCartItem1 = new ShoppingCartItem(
	array(
		"Value" => 700,
		"Description" => "This is one item",
		"Quantity" => 1,
		"ImageURL" => "https://somemerchant.com/someimage"
	)
);

$shoppingCartItem2 = new ShoppingCartItem(
	array(
		"Value" => 300,
		"Description" => "This is another item",
		"Quantity" => 1,
		"ImageURL" => "https://somemerchant.com/someotherimage"
	)
);

$shoppingCart = new ShoppingCart(
	array(
		"CurrencyCode" => "USD",
		"Subtotal" => 1000,
		"ShoppingCartItem" => array($shoppingCartItem1, $shoppingCartItem2)
	)
);

$shoppingCartRequest = new ShoppingCartRequest(
	array(
		"OAuthToken" => $requestToken,
		"OriginUrl" => $callbackDomain,
		"ShoppingCart" => $shoppingCart,
	)
);

//Call the ShoppingCartService with required params
$shoppingCartResponse = ShoppingCartApi::create($shoppingCartRequest);

6. Call Merchant Initialization Service

The Merchant Initialization Service is used to secure Lightbox connections between the merchant site and MasterPass. The OriginUrl identifies the origin of the page that will invoke the Lightbox. This service requires the request token from Step 4.

The Merchant Initialization Service must be called before creating the Buy with MasterPass button.

//Create an instance of MerchantInitializationRequest
$merchantInitializationRequest = new MerchantInitializationRequest(
	array(
		"OriginUrl" => "https://somemerchant.com",
		"OAuthToken" => $requestToken
	)
);

//Call the MerchantInitializationApi with required params
$merchantInitializationResponse = MerchantInitializationApi::create($merchantInitializationRequest);

7. Create Buy With MasterPass Button

Import jQuery, and add the MasterPass Integration Script for either the sandbox or the production environment

 <!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

On the Place Order page of the merchant's website, create the Buy with MasterPass button using the cardId, addressId, and rewardId from Step 3 and the request token from Step 4.

<script type="text/javascript" language="Javascript">
MasterPass.client.checkout({
     "requestToken":"insert_request_token_here",                       //required
     "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm", //required
     "merchantCheckoutId":"insert_checkout_id_here",                   //required
     "cardId":"insert_selected_card_id_here",                          //required
     "shippingId":"insert_selected_shipping_address_id_here",          //required
     "precheckoutTransactionId":"insert_prechechout_txn_id_here",      //required
     "walletName":"insert_wallet_name_here",                           //required
     "consumerWalletId":"insert_consumer_walletid_here",               //required
     "loyaltyId":"insert_loyalty_id_here",                             //optional
     "requireShippingDestination": "true"                              //optional                                                                                                                                                                 
     "version":"v6",                                                   //optional
     "successCallback": function(mpLightboxResponse){ ... },           //optional
     "failureCallback": function(mpLightboxResponse){ ... },           //optional
     "cancelCallback": function(mpLightboxResponse){ ... }             //optional
});
</script>

• requestToken: The request token generated in Step 4.
• callbackUrl: The merchant URL to which the browser will redirect when the Lightbox closes.
• merchantCheckoutId: The unique checkout identifier obtained during the Merchant Onboarding process.
• cardId: The identifier of the selected card collected in Step 3.
• shippingId: The identifier of the shipping information collected in Step 3.
• precheckoutTransactionId: The pre-checkout transaction identifier collected in Step 3.
• walletName: The consumer's wallet name collected in Step 3.
• consumerWalletId: The consumer's wallet identifier collected in Step 3.
• loyaltyId: The rewardId, optionally collected in Step 3.
• requireShippingDestination: Denotes whether the consumer's shipping information is required.
• version: MasterPass API version (default is v6).
• successCallback: The function that will be called if the MasterPass flow ends successfully.
• failureCallback: The function that will be called if the MasterPass flow ends in failure.
• cancelCallback: The function that will be called if the user cancels the MasterPass flow.

8. Redirect to callback URL or call callback function

After the consumer completes checkout, MasterPass returns data to the merchant. By default, MasterPass redirects the browser to the callback URL, returning the data via URL parameters. Optionally, if callback functions were provided in Step 4, MasterPass returns control to the page that initiated the Lightbox, and the data is passed to the callback function.

Under certain conditions, the MasterPass UI may be forced to run in Full Screen display instead of launching the Lightbox. When this occurs, the browser will redirected to the callback URL when the MasterPass flow is complete, even if callback functions were supplied.

On Success

On Success, MasterPass returns the following parameters:

• mpstatus: String that indicates whether the MasterPass flow resulted in success, failure, or cancel.
• checkout_resource_url: The API URL that will be used to retrieve checkout information in Step 10.
• oauth_verifier: The verifier token that is used in conjunction with the request token to retrieve the access token in Step 9.
• oauth_token: The request token that is used in conjunction with the verifier token to retrieve the access token in Step 9. This token has the same value as the request token that is generated in Step 1.

Example Callback URL (Success)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass\%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw
&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13
&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc

Example Callback URL (Cancel)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

Example Callback URL (Failure)

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

Example Callback Function (Success)

function handleCallbackSuccess (data) {
    callYourServerWith(data.oauth_token, data.oauth_verifier, data.checkout_resource_url);
}

9. Call Access Token Service

If the checkout was completed successfully, call the Access Token Service to retrieve an access token. You will need the request token and the verifier token received in Step 8.

As there is no need to retrieve a long access token again, only this one call to the Access Token Service will be made.

$accessTokenResponse = AccessTokenApi::create($requestToken, $verifierToken);
$accessToken = $accessTokenResponse->getOauthToken();

10. Retrieve Payment, Shipping Data, Rewards and 3-D Secure Details

Use the Checkout Resource URL received in Step 8 and the access token from Step 9 to retrieve the constomer’s payment, shipping, reward and 3-D Secure information from MasterPass.

$explodedURL = explode("/", $checkoutResourceUrl);
$checkoutId = array_pop($explodedURL);
if(strpos($checkoutId, "?") !== false){
	$checkoutId = explode($checkoutId, "?")[0];
}

$logger->info($checkoutId);

$checkout = CheckoutApi::show($checkoutId, $accessToken);

$card = $checkout->getCard();
$billingAddress = $card->getBillingAddress();
$contact = $checkout->getContact();
$authOptions = checkout->getAuthenticationOptions(); 
$preCheckoutTransactionId = checkout->getPreCheckoutTransactionId(); 
$rewardProgram = checkout->getRewardProgram(); 
$shippingAddress = checkout->getShippingAddress();
$transactionId = checkout->getTransactionId();
$walletId = checkout->getWalletID();

11. Process Payment through a payment gateway

Using the data retrieved in Step 10, process the payment through the merchant's payment gateway.

12. Log Transactions with MasterPass

After the payment has been processed in Step 11, make a service call to communicate the result of the transaction to MasterPass.

//Create an instance of MerchantTransactions
$merchantTransaction = new MerchantTransaction(
	array(
		"TransactionId" => "4549794",
		"ConsumerKey" => "0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d", //generated during onboarding process
		"Currency" => "USD",
		"OrderAmount" => 500, // total charged to card
		"TransactionStatus" => "Success",
		"ApprovalCode" => "888888", // authorization code returned by payment gateway
		"PrecheckoutTransactionId" => "a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947",
		"ExpressCheckoutIndicator" => false,
		"PurchaseDate" => date("Y/m/d H:i:s")
	)
);
$request = new MerchantTransactions(array("MerchantTransactions" => array($merchantTransaction)));

//Call the PostbackService with required params
$response = PostbackApi::create($request);

callback_url = "https://www.somemerchant.com/checkoutconfirm.htm"
pairing_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
pairing_request_token = pairing_token_response.oauth_token;

request_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
request_token = request_token_response.oauth_token;

//Create an instance of ShoppingCartRequest
ShoppingCartRequest shoppingCartRequest = new ShoppingCartRequest();
ShoppingCart shoppingCart = new ShoppingCart();
List<ShoppingCartItem> shoppingCartItems = new List<ShoppingCartItem>();
shoppingCartItems.Add(new ShoppingCartItem
{
    Value = 1900L,
    Description = "This is one item",
    Quantity = 1
});
shoppingCartItems.Add(new ShoppingCartItem
{
    ImageURL = "https://somemerchant.com/someimage",
    Value = 10000L,
    Description = "Five items",
    Quantity = 5
});

shoppingCart.Subtotal = 11900L;
shoppingCart.CurrencyCode = "USD";
shoppingCart.ShoppingCartItem = shoppingCartItems;

shoppingCartRequest.ShoppingCart = shoppingCart;
shoppingCartRequest.OAuthToken = request_token;

//Call the ShoppingCartService with required params
ShoppingCartResponse shoppingCartResponse = ShoppingCartApi.Create(shoppingCartRequest);

//Create an instance of MerchantInitializationRequest
MerchantInitializationRequest merchantInitializationRequest = new MerchantInitializationRequest
{
    OriginUrl = "https://somemerchant.com",
    OAuthToken = request_token
};

//Call the MerchantInitializationApi with required params
MerchantInitializationResponse merchantInitializationResponse = MerchantInitializationApi.Create(merchantInitializationRequest);

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png"/>

<!-- url to jquery 1.10.2 -->
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
  <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
  <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

<script type="text/javascript" language="Javascript">
    MasterPass.client.checkout({
        "requestPairing":true,                                                      //required
        "requestToken":"insert_checkout_request_token_here",                        //required
        "pairingRequestToken":"insert_pairing_request_token_here",                  //required
        "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",           //required
        "merchantCheckoutId":"insert_checkout_id_here",                             //required
        "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],      //required
        "requestExpressCheckout": true,                                             //required
        "allowedCardTypes":["master","amex","diners","discover","maestro","visa"],  //optional
        "version":"v6",                                                             //optional
        "successCallback": function(mpLightboxResponse){ ... },                     //optional
        "failureCallback": function(mpLightboxResponse){ ... },                     //optional
        "cancelCallback": function(mpLightboxResponse){ ... }                       //optional
    });
</script>

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F
10706241%3Fwallet%3Dphw
&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458
&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=cancel

http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=failure

AccessTokenResponse checkoutAccessTokenResponse = AccessTokenApi.Create(oauth_checkout_request_token, oauth_checkout_verifier_token);
string checkout_access_token = checkoutAccessTokenResponse.OauthToken;

AccessTokenResponse longAccessTokenResponse = AccessTokenApi.Create(oauth_pairing_request_token, oauth_pairing_verifier_token);
string long_access_token = longAccessTokenResponse.OauthToken; // store for future requests

string checkoutId = checkoutResourceUrl.IndexOf('?') != -1 ? checkoutResourceUrl.Substring(checkoutResourceUrl.LastIndexOf('/') + 1).Split('?')[0] : checkoutResourceUrl.Substring(checkoutResourceUrl.LastIndexOf('/') + 1);

Checkout checkout = CheckoutApi.Show(checkoutId, accessToken);

Card card = checkout.Card;
Address billingAddress = card.BillingAddress;
Contact contact = checkout.Contact;
AuthenticationOptions authOptions = checkout.AuthenticationOptions;
string preCheckoutTransactionId = checkout.PreCheckoutTransactionId;
RewardProgram rewardProgram = checkout.RewardProgram;
ShippingAddress shippingAddress = checkout.ShippingAddress;
string transactionId = checkout.TransactionId;
string walletId = checkout.WalletID;

//Create an instance of MerchantTransactions
MerchantTransactions objMerchantTransactions = new MerchantTransactions();
List<MerchantTransaction> merchantTransactions = new List<MerchantTransaction>();
MerchantTransaction merchantTransaction = new MerchantTransaction
{
    TransactionId = "4549794", // from Step 7
    PurchaseDate = "2014-08-01T14:52:57.539-05:00",
    ExpressCheckoutIndicator = false,
    ApprovalCode = "888888",  // authorization code returned by payment gateway
    TransactionStatus = "Success",
    OrderAmount = 1229L, // total charged to card
    PreCheckoutTransactionId = "a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947",
    Currency = "USD",
    ConsumerKey = "0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d" //generated during onboarding process
};

merchantTransactions.Add(merchantTransaction);

objMerchantTransactions._MerchantTransactions = merchantTransactions;

//Call the PostbackService with required params
MerchantTransactions response = PostbackApi.Create(objMerchantTransactions);

string callback_url = "https://www.somemerchant.com/pairingcomplete.htm";
RequestTokenResponse requestTokenResponse = RequestTokenApi.Create(callback_url);
string pairing_request_token = requestTokenResponse.OauthToken;

//Create an instance of MerchantInitializationRequest
MerchantInitializationRequest merchantInitializationRequest = new MerchantInitializationRequest
{
    OriginUrl = "https://somemerchant.com",
    OAuthToken = pairing_request_token
};
//Call the MerchantInitializationApi with required params
MerchantInitializationResponse merchantInitializationResponse = MerchantInitializationApi.Create(merchantInitializationRequest);

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mp_connect_with_button_126px.png"/>

<!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

<script type="text/javascript" language="Javascript">
    MasterPass.client.connect({
        "requestPairing":true,                                                  //required
        "pairingRequestToken":"insert_pairing_request_token_here",              //required
        "callbackUrl":"http://www.somemerchant.com/pairingcomplete.htm",        //required
        "merchantCheckoutId":"insert_checkout_id_here",                         //required
        "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],  //required
        "requestExpressCheckout":true,                                          //required
        "version":"v6",                                                         //optional
        "successCallback": function(mpLightboxResponse){ ... },                 //optional
        "failureCallback": function(mpLightboxResponse){ ... },                 //optional
        "cancelCallback": function(mpLightboxResponse){ ... }                   //optional
    });
</script>

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=success
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=cancel

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=failure

function handleCallbackSuccess (data) {
    document.getElementById('pairingToken').value=data.pairing_token;
    document.getElementById('pairingVerifer').value=data.pairing_verifier;
}

AccessTokenResponse accessTokenResponse = AccessTokenApi.create(pairing_request_token, pairing_verifier_token);
String long_access_token = accessTokenResponse.getOauthToken(); // store for future requests

string[] requestedDataTypes = { "REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD" };

PrecheckoutDataRequest preCheckoutDataRequest = new PrecheckoutDataRequest();
List<PairingDataType> lstPairingDataType = new List<PairingDataType>();
//foreach (var item in requestedDataTypes)
//{
//    lstPairingDataType.Add(new PairingDataType
//    {
//        Type = item
//    });
//}
lstPairingDataType = requestedDataTypes.Select(item => new PairingDataType() { Type = item }).ToList();

preCheckoutDataRequest.PairingDataTypes.PairingDataType = lstPairingDataType;

PrecheckoutDataResponse response = PrecheckoutDataApi.Create(long_access_token, preCheckoutDataRequest);

ExpressCheckoutRequest expressCheckoutRequest = new ExpressCheckoutRequest
{
    PrecheckoutTransactionId = "insert_precheckoutTransactionId_here",  // from precheckout data
    MerchantCheckoutId = "insert_checkoutId_here",
    OriginUrl = "http://www.somemerchant.com",
    CurrencyCode = "USD",
    AdvancedCheckoutOverride = false, // set to true to disable 3-DS authentication
    OrderAmount = "1299",
    DigitalGoods = false,
    CardId = "consumer_selected_cardId",
    ShippingAddressId = "consumer_selected_shippingAddressId",
    RewardProgramId = "consumer_selected_rewardId",
};
ExpressCheckoutResponse response = ExpressCheckoutApi.Create("insert_longAccessToken_here", expressCheckoutRequest);

Checkout checkout = response.Checkout;

Card card = checkout.Card;
Address billingAddress = card.BillingAddress;
Contact contact = checkout.Contact;
AuthenticationOptions authOptions = checkout.AuthenticationOptions;
string preCheckoutTransactionId = checkout.PreCheckoutTransactionId;
RewardProgram rewardProgram = checkout.RewardProgram;
ShippingAddress shippingAddress = checkout.ShippingAddress;
string transactionId = checkout.TransactionId;
string walletId = checkout.WalletID;

//Create an instance of MerchantTransactions
MerchantTransactions objMerchantTransactions = new MerchantTransactions();
List<MerchantTransaction> merchantTransactions = new List<MerchantTransaction>();
MerchantTransaction merchantTransaction = new MerchantTransaction
{
    TransactionId = "4549794", // from Step 7
    PurchaseDate = "2014-08-01T14:52:57.539-05:00",
    ExpressCheckoutIndicator = true, // mark this as true
    ApprovalCode = "888888",  // authorization code returned by payment gateway
    TransactionStatus = "Success",
    OrderAmount = 1229L, // total charged to card
    PreCheckoutTransactionId = "a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947",
    Currency = "USD",
    ConsumerKey = "0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d" //generated during onboarding process
};

merchantTransactions.Add(merchantTransaction);

objMerchantTransactions._MerchantTransactions = merchantTransactions;

//Call the PostbackService with required params
MerchantTransactions response = PostbackApi.Create(objMerchantTransactions);

ExpressCheckoutResponse response = ExpressCheckoutApi.Create("insert_longAccessToken_here", expressCheckoutRequest);

bool expressSecurityRequired = false;
if (response.Errors != null && response.Errors.Error.Count > 0)
{
    expressSecurityRequired = response.Errors.Error.Any(x => x.Source == "3DS Needed");
}

string callback_url = "https://www.somemerchant.com/checkoutconfirm.htm";
RequestTokenResponse requestTokenResponse = RequestTokenApi.Create(callback_url);
string request_token = requestTokenResponse.OauthToken;

//Create an instance of MerchantInitializationRequest
MerchantInitializationRequest merchantInitializationRequest = new MerchantInitializationRequest
{
    OriginUrl = "https://somemerchant.com",
    OAuthToken = request_token
};

//Call the MerchantInitializationApi with required params
MerchantInitializationResponse merchantInitializationResponse = MerchantInitializationApi.Create(merchantInitializationRequest);

 <!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

<script type="text/javascript" language="Javascript">

MasterPass.client.cardSecurity({
    "requestToken":"insert_request_token_here",                       //required
    "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm", //required
    "merchantCheckoutId":"insert_checkout_id_here",                   //required
    "precheckoutTransactionId":"insert_prechechout_txn_id_here",      //required
    "successCallback": function(mpLightboxResponse){ ... },           //optional
    "failureCallback": function(mpLightboxResponse){ ... },           //optional
    "cancelCallback": function(mpLightboxResponse){ ... }             //optional
});

</script>

http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=success

http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=cancel

http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=failure

function handleCallbackSuccess (data) {
    callYourServerWith(data.mpstatus);
}

ExpressCheckoutRequest expressCheckoutRequest = new ExpressCheckoutRequest
{
    PrecheckoutTransactionId = "insert_precheckoutTransactionId_here",  // from precheckout data
    MerchantCheckoutId = "insert_checkoutId_here",
    OriginUrl = "http://www.somemerchant.com",
    CurrencyCode = "USD",
    AdvancedCheckoutOverride = false, // set to true to disable 3-DS authentication
    OrderAmount = "1299",
    DigitalGoods = false,
    CardId = "consumer_selected_cardId",
    ShippingAddressId = "consumer_selected_shippingAddressId",
    RewardProgramId = "consumer_selected_rewardId",
};
ExpressCheckoutResponse response = ExpressCheckoutApi.Create("insert_longAccessToken_here", expressCheckoutRequest);

Checkout checkout = response.Checkout;

Card card = checkout.Card;
Address billingAddress = card.BillingAddress;
Contact contact = checkout.Contact;
AuthenticationOptions authOptions = checkout.AuthenticationOptions;
string preCheckoutTransactionId = checkout.PreCheckoutTransactionId;
RewardProgram rewardProgram = checkout.RewardProgram;
ShippingAddress shippingAddress = checkout.ShippingAddress;
string transactionId = checkout.TransactionId;
string walletId = checkout.WalletID;

callback_url = "https://www.somemerchant.com/checkoutconfirm.htm"
pairing_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
pairing_request_token = pairing_token_response.oauth_token;

request_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
request_token = request_token_response.oauth_token;

shopping_cart_request = MastercardMasterpassMerchant::ShoppingCartRequest.new(
    :o_auth_token => request_token,
    :shopping_cart => MastercardMasterpassMerchant::ShoppingCart.new(
        :currency_code => 'USD',
        :subtotal => '11900',
        :shopping_cart_item => [
            MastercardMasterpassMerchant::ShoppingCartItem.new(
                :description => 'One Item',
                :quantity => 1,
                :value => 1900
            ),
            MastercardMasterpassMerchant::ShoppingCartItem.new(
                :description => 'Five of an Item',
                :quantity => 5,
                :value => 10000,
                :image_url => 'http://somemerchant.com/someimage'
            )
        ]
    )
)

shopping_cart_response = MastercardMasterpassMerchant::Api::ShoppingCartApi.create(shopping_cart_request)

merchant_init_request = MastercardMasterpassMerchant::MerchantInitializationRequest.new(
    :o_auth_token => request_token,
    :origin_url => 'https://somemerchant.com'
)

merchant_init_response = MastercardMasterpassMerchant::Api::MerchantInitializationApi.create(merchant_init_request)

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png"/>

<!-- url to jquery 1.10.2 -->
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
  <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
  <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

<script type="text/javascript" language="Javascript">
    MasterPass.client.checkout({
        "requestPairing":true,                                                      //required
        "requestToken":"insert_checkout_request_token_here",                        //required
        "pairingRequestToken":"insert_pairing_request_token_here",                  //required
        "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",           //required
        "merchantCheckoutId":"insert_checkout_id_here",                             //required
        "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],      //required
        "requestExpressCheckout": true,                                             //required
        "allowedCardTypes":["master","amex","diners","discover","maestro","visa"],  //optional
        "version":"v6",                                                             //optional
        "successCallback": function(mpLightboxResponse){ ... },                     //optional
        "failureCallback": function(mpLightboxResponse){ ... },                     //optional
        "cancelCallback": function(mpLightboxResponse){ ... }                       //optional
    });
</script>

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F
10706241%3Fwallet%3Dphw
&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458
&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

access_token_response = MastercardCoreSdk::Api::AccessTokenApi.create(verifier_token, request_token)
access_token = access_token_response.oauth_token

long_access_token_response = MastercardCoreSdk::Api::AccessTokenApi.create(pairing_verifier_token, pairing_request_token)
long_access_token = long_access_token_response.oauth_token

start_index = checkout_resource_url.rindex('/') + 1
end_index = checkout_resource_url.index('?').nil? ? -1 : checkout_resource_url.index('?')
path_id = checkout_resource_url[start_index..end_index]

checkout = MastercardMasterpassMerchant::Api::CheckoutApi.show(path_id, access_token)
card = checkout.card
billing_address = card.billing_address
contact = checkout.contact
auth_options = checkout.authentication_options
precheckout_transaction_id = checkout.pre_checkout_transaction_id
reward_program = checkout.reward_program
shipping_address = checkout.shipping_address
transaction_id = checkout.transaction_id
wallet_id = checkout.wallet_id

merchant_transactions = MastercardMasterpassMerchant::MerchantTransactions.new(
    :merchant_transactions => [
        MastercardMasterpassMerchant::MerchantTransaction.new(
            :transaction_id => 4549794,
            :consumer_key => '0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d',
            :currency => 'USD',
            :order_amount => 1800,
            :transaction_status => 'Success',
            :approval_code => '888888',
            :pre_checkout_transaction_id => 'a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947',
            :express_checkout_indicator => false,
            :purchase_date => '2016-06-23T15:09:32+00:00'
        )
    ]
)

merchant_trans_response = MastercardMasterpassMerchant::Api::PostbackApi.create(merchant_transactions)

callback_url = "https://www.somemerchant.com/checkoutconfirm.htm"
pairing_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
pairing_request_token = pairing_token_response.oauth_token;

merchant_init_request = MastercardMasterpassMerchant::MerchantInitializationRequest.new(
    :o_auth_token => pairing_request_token,
    :origin_url => 'https://somemerchant.com'
)

merchant_init_response = MastercardMasterpassMerchant::Api::MerchantInitializationApi.create(merchant_init_request)

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mp_connect_with_button_126px.png"/>

<!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

<script type="text/javascript" language="Javascript">
    MasterPass.client.connect({
        "requestPairing":true,                                                  //required
        "pairingRequestToken":"insert_pairing_request_token_here",              //required
        "callbackUrl":"http://www.somemerchant.com/pairingcomplete.htm",        //required
        "merchantCheckoutId":"insert_checkout_id_here",                         //required
        "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],  //required
        "requestExpressCheckout":true,                                          //required
        "version":"v6",                                                         //optional
        "successCallback": function(mpLightboxResponse){ ... },                 //optional
        "failureCallback": function(mpLightboxResponse){ ... },                 //optional
        "cancelCallback": function(mpLightboxResponse){ ... }                   //optional
    });
</script>

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=success
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=cancel

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=failure

function handleCallbackSuccess (data) {
    document.getElementById('pairingToken').value=data.pairing_token;
    document.getElementById('pairingVerifer').value=data.pairing_verifier;
}

long_access_token_response = MastercardCoreSdk::Api::AccessTokenApi.create(pairing_verifier_token, pairing_request_token)
long_access_token = long_access_token_response.oauth_token

requested_data_types = ['REWARD_PROGRAM', 'ADDRESS', 'PROFILE', 'CARD']
pairing_data_types = []
requested_data_types.each do |data_type|
  pairing_data_type = MastercardMasterpassMerchant::PairingDataType.new
  pairing_data_type.type = data_type
  pairing_data_types.append(pairing_data_type)
end

pre_checkout_data_request = MastercardMasterpassMerchant::PrecheckoutDataRequest.new(
    :pairing_data_types => MastercardMasterpassMerchant::PairingDataTypes.new(
        :pairing_data_type => pairing_data_types
    )
)

response = MastercardMasterpassMerchant::Api::PrecheckoutDataApi.create(long_access_token, pre_checkout_data_request)

express_checkout_request = MastercardMasterpassMerchant::ExpressCheckoutRequest.new(
    :merchant_checkout_id => 'insert_checkoutId_here',
    :precheckout_transaction_id => 'insert_precheckoutTransactionId_here',
    :currency_code => 'USD',
    :order_amount => 1299,
    :card_id => 'consumer_selected_cardId',
    :digital_goods => false,
    :shipping_address_id => 'consumer_selected_shippingAddressId',
    :reward_program_id => 'consumer_selected_rewardId',
    :advanced_checkout_override => false,
    :origin_url => 'http://somemerchant.com'
)

express_checkout_response = MastercardMasterpassMerchant::Api::ExpressCheckoutApi.create(long_access_token, express_checkout_request)
checkout = express_checkout_response.checkout
card = checkout.card
billing_address = card.billing_address
contact = checkout.contact
auth_options = checkout.authentication_options
precheckout_transaction_id = checkout.pre_checkout_transaction_id
reward_program = checkout.reward_program
shipping_address = checkout.shipping_address
transaction_id = checkout.transaction_id
wallet_id = checkout.wallet_id

merchant_transactions = MastercardMasterpassMerchant::MerchantTransactions.new(
    :merchant_transactions => [
        MastercardMasterpassMerchant::MerchantTransaction.new(
            :transaction_id => 4549794,
            :consumer_key => '0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d',
            :currency => 'USD',
            :order_amount => 1800,
            :transaction_status => 'Success',
            :approval_code => '888888',
            :pre_checkout_transaction_id => 'a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947',
            :express_checkout_indicator => false,
            :purchase_date => '2016-06-23T15:09:32+00:00'
        )
    ]
)

merchant_trans_response = MastercardMasterpassMerchant::Api::PostbackApi.create(merchant_transactions)

if !merchant_trans_response.errors.nil? && merchant_trans_response.errors.error.size > 0
  merchant_trans_response.errors.error.each do |error|
    if error.source == '3DS Needed'
        express_security_required = true
    end
  end
end

callback_url = "https://www.somemerchant.com/checkoutconfirm.htm"
request_token_response = MastercardCoreSdk::Api::RequestTokenApi.create(callback_url)
request_token = request_token_response.oauth_token;

merchant_init_request = MastercardMasterpassMerchant::MerchantInitializationRequest.new(
    :o_auth_token => request_token,
    :origin_url => 'https://somemerchant.com'
)

merchant_init_response = MastercardMasterpassMerchant::Api::MerchantInitializationApi.create(merchant_init_request)

 <!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

<script type="text/javascript" language="Javascript">

MasterPass.client.cardSecurity({
    "requestToken":"insert_request_token_here",                       //required
    "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm", //required
    "merchantCheckoutId":"insert_checkout_id_here",                   //required
    "precheckoutTransactionId":"insert_prechechout_txn_id_here",      //required
    "successCallback": function(mpLightboxResponse){ ... },           //optional
    "failureCallback": function(mpLightboxResponse){ ... },           //optional
    "cancelCallback": function(mpLightboxResponse){ ... }             //optional
});

</script>

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

function handleCallbackSuccess (data) {
    callYourServerWith(data.mpstatus);
}

express_checkout_request = MastercardMasterpassMerchant::ExpressCheckoutRequest.new(
    :merchant_checkout_id => 'insert_checkoutId_here',
    :precheckout_transaction_id => 'insert_precheckoutTransactionId_here',
    :currency_code => 'USD',
    :order_amount => 1299,
    :card_id => 'consumer_selected_cardId',
    :digital_goods => false,
    :shipping_address_id => 'consumer_selected_shippingAddressId',
    :reward_program_id => 'consumer_selected_rewardId',
    :advanced_checkout_override => false,
    :origin_url => 'http://somemerchant.com'
)

express_checkout_response = MastercardMasterpassMerchant::Api::ExpressCheckoutApi.create(long_access_token, express_checkout_request)
checkout = express_checkout_response.checkout
card = checkout.card
billing_address = card.billing_address
contact = checkout.contact
auth_options = checkout.authentication_options
precheckout_transaction_id = checkout.pre_checkout_transaction_id
reward_program = checkout.reward_program
shipping_address = checkout.shipping_address
transaction_id = checkout.transaction_id
wallet_id = checkout.wallet_id

$callbackUrl = "https://www.somemerchant.com/checkoutconfirm.htm";

$pairingResponse = RequestTokenApi::create($callbackUrl);
$pairingRequestToken = $pairingResponse->getOauthToken();

$checkoutResponse = RequestTokenApi::create($callbackUrl);
$checkoutRequestToken = $checkoutResponse::getOauthToken();

//Build Out ShoppingCartRequest object
$shoppingCartItem1 = new ShoppingCartItem(
	array(
		"Value" => 700,
		"Description" => "This is one item",
		"Quantity" => 1,
		"ImageURL" => "https://somemerchant.com/someimage"
	)
);

$shoppingCartItem2 = new ShoppingCartItem(
	array(
		"Value" => 300,
		"Description" => "This is another item",
		"Quantity" => 1,
		"ImageURL" => "https://somemerchant.com/someotherimage"
	)
);

$shoppingCart = new ShoppingCart(
	array(
		"CurrencyCode" => "USD",
		"Subtotal" => 1000,
		"ShoppingCartItem" => array($shoppingCartItem1, $shoppingCartItem2)
	)
);

$shoppingCartRequest = new ShoppingCartRequest(
	array(
		"OAuthToken" => $requestToken,
		"OriginUrl" => $callbackDomain,
		"ShoppingCart" => $shoppingCart,
	)
);

//Call the ShoppingCartService with required params
$shoppingCartResponse = ShoppingCartApi::create($shoppingCartRequest);

//Create an instance of MerchantInitializationRequest
$merchantInitializationRequest = new MerchantInitializationRequest(
	array(
		"OriginUrl" => "https://somemerchant.com",
		"OAuthToken" => $checkoutRequestToken
	)
);

//Call the MerchantInitializationApi with required params
$merchantInitializationResponse = MerchantInitializationApi::create($merchantInitializationRequest);

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png"/>

<!-- url to jquery 1.10.2 -->
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
  <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
  <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

<script type="text/javascript" language="Javascript">
    MasterPass.client.checkout({
        "requestPairing":true,                                                      //required
        "requestToken":"insert_checkout_request_token_here",                        //required
        "pairingRequestToken":"insert_pairing_request_token_here",                  //required
        "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",           //required
        "merchantCheckoutId":"insert_checkout_id_here",                             //required
        "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],      //required
        "requestExpressCheckout": true,                                             //required
        "allowedCardTypes":["master","amex","diners","discover","maestro","visa"],  //optional
        "version":"v6",                                                             //optional
        "successCallback": function(mpLightboxResponse){ ... },                     //optional
        "failureCallback": function(mpLightboxResponse){ ... },                     //optional
        "cancelCallback": function(mpLightboxResponse){ ... }                       //optional
    });
</script>

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success
&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F
10706241%3Fwallet%3Dphw
&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458
&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

$checkoutAccessTokenResponse = AccessTokenApi::create(oauthCheckoutRequestToken, oauthCheckoutVerifierToken);
$checkoutAccessToken = checkoutAccessTokenResponse->getOauthToken();

$longAccessTokenResponse = AccessTokenApi::create(oauthPairingRequestToken, oauthPairingVerifierToken);
$longAccessToken = longAccessTokenResponse->getOauthToken(); // store for future requests

$explodedURL = explode("/", $checkoutResourceUrl);
$checkoutId = array_pop($explodedURL);
if(strpos($checkoutId, "?") !== false){
	$checkoutId = explode($checkoutId, "?")[0];
}

$logger->info($checkoutId);

$checkout = CheckoutApi::show($checkoutId, $accessToken);

$card = $checkout->getCard();
$billingAddress = $card->getBillingAddress();
$contact = $checkout->getContact();
$authOptions = checkout->getAuthenticationOptions(); 
$preCheckoutTransactionId = checkout->getPreCheckoutTransactionId(); 
$rewardProgram = checkout->getRewardProgram(); 
$shippingAddress = checkout->getShippingAddress();
$transactionId = checkout->getTransactionId();
$walletId = checkout->getWalletID();

//Create an instance of MerchantTransactions
$merchantTransaction = new MerchantTransaction(
	array(
		"TransactionId" => "4549794",
		"ConsumerKey" => "0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d", //generated during onboarding process
		"Currency" => "USD",
		"OrderAmount" => 500, // total charged to card
		"TransactionStatus" => "Success",
		"ApprovalCode" => "888888", // authorization code returned by payment gateway
		"PrecheckoutTransactionId" => "a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947",
		"ExpressCheckoutIndicator" => false,
		"PurchaseDate" => date("Y/m/d H:i:s")
	)
);
$request = new MerchantTransactions(array("MerchantTransactions" => array($merchantTransaction)));

//Call the PostbackService with required params
$response = PostbackApi::create($request);

$callbackUrl = "https://www.somemerchant.com/pairingcomplete.htm";
$requestTokenResponse = RequestTokenApi::create($callbackUrl);
$pairingRequestToken = $requestTokenResponse->getOauthToken();

//Create an instance of MerchantInitializationRequest
$merchantInitializationRequest = new MerchantInitializationRequest(
	array(
		"OriginUrl" => "https://somemerchant.com",
		"OAuthToken" => $pairingRequestToken
	)
);

//Call the MerchantInitializationApi with required params
$merchantInitializationResponse = MerchantInitializationApi::create($merchantInitializationRequest);

<img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mp_connect_with_button_126px.png"/>

<!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

<script type="text/javascript" language="Javascript">
    MasterPass.client.connect({
        "requestPairing":true,                                                  //required
        "pairingRequestToken":"insert_pairing_request_token_here",              //required
        "callbackUrl":"http://www.somemerchant.com/pairingcomplete.htm",        //required
        "merchantCheckoutId":"insert_checkout_id_here",                         //required
        "requestedDataTypes":["REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD"],  //required
        "requestExpressCheckout":true,                                          //required
        "version":"v6",                                                         //optional
        "successCallback": function(mpLightboxResponse){ ... },                 //optional
        "failureCallback": function(mpLightboxResponse){ ... },                 //optional
        "cancelCallback": function(mpLightboxResponse){ ... }                   //optional
    });
</script>

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=success
&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13
&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=cancel

http://www.somemerchant.com/pairingcomplete.htm
?mpstatus=failure

function handleCallbackSuccess (data) {
    document.getElementById('pairingToken').value=data.pairing_token;
    document.getElementById('pairingVerifer').value=data.pairing_verifier;
}

$accessTokenResponse = AccessTokenApi::create($pairingRequestToken, $pairingVerifierToken);
$longAccessToken = $accessTokenResponse->getOauthToken(); // store for future requests

$requestedDataTypes = array("REWARD_PROGRAM", "ADDRESS", "PROFILE", "CARD");

$preCheckoutDataRequest = new PreCheckoutDataRequest();
$pairingDataTypes = new PairingDataTypes();

foreach ($requestedDataTypes as $pairingType){
	$newPairingType = new PairingDataType(
		array(
			"Type" => $pairingType
		)
	);
	$pairingDataTypes->setPairingDataType = $newPairingType;
}

$preCheckoutDataRequest->setPairingDataTypes($pairingDataTypes);

$preCheckoutDataResponse = PrecheckoutDataApi::create($longAccessToken, $preCheckoutDataRequest);

$expressCheckoutRequest = new ExpressCheckoutRequest();

$expressCheckoutRequest->setMerchantCheckoutId("insert_checkoutId_here");
$expressCheckoutRequest->setPrecheckoutTransactionId("insert_precheckoutTransactionId_here"); // from precheckout data
$expressCheckoutRequest->setCurrencyCode("USD");
$expressCheckoutRequest->setCardId("consumer_selected_cardId");
$expressCheckoutRequest->setOriginUrl("http://www.somemerchant.com");
$expressCheckoutRequest->setAdvancedCheckoutOverride(false);
$expressCheckoutRequest->setOrderAmount("1299");
$expressCheckoutRequest->setDigitalGoods(false);
$expressCheckoutRequest->setShippingAddressId("consumer_selected_shippingAddressId");
$expressCheckoutRequest->setRewardProgramId("consumer_selected_rewardId");

$response = ExpressCheckoutApi::create("insert_longAccessToken_here", $expressCheckoutRequest);

$checkout = response->getCheckout();

$card = $checkout->getCard();
$billingAddress = $card->getBillingAddress();
$contact = $checkout->getContact();
$authOptions = checkout->getAuthenticationOptions(); 
$preCheckoutTransactionId = checkout->getPreCheckoutTransactionId(); 
$rewardProgram = checkout->getRewardProgram(); 
$shippingAddress = checkout->getShippingAddress();
$transactionId = checkout->getTransactionId();
$walletId = checkout->getWalletID();

//Create an instance of MerchantTransactions
$merchantTransaction = new MerchantTransaction(
	array(
		"TransactionId" => "4549794",
		"ConsumerKey" => "0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d", //generated during onboarding process
		"Currency" => "USD",
		"OrderAmount" => 500, // total charged to card
		"TransactionStatus" => "Success",
		"ApprovalCode" => "888888", // authorization code returned by payment gateway
		"PrecheckoutTransactionId" => "a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947",
		"ExpressCheckoutIndicator" => false,
		"PurchaseDate" => date("Y/m/d H:i:s")
	)
);
$request = new MerchantTransactions(array("MerchantTransactions" => array($merchantTransaction)));

//Call the PostbackService with required params
$response = PostbackApi::create($request);

$response = ExpressCheckoutApi::create("insert_longAccessToken_here", $expressCheckoutRequest);

$expressSecurityRequired = false;

foreach ($response->getErrors()->getError() as $error) {
	if (error->getSource() === "3DS Needed") {
		$expressSecurityRequired = true;
	}
}

$callbackUrl = "https://www.somemerchant.com/checkoutconfirm.htm";
$requestTokenResponse = RequestTokenApi::create($callbackUrl);
$requestToken = $requestTokenResponse->getOauthToken();

//Create an instance of MerchantInitializationRequest
$merchantInitializationRequest = new MerchantInitializationRequest(
	array(
		"OriginUrl" => "https://somemerchant.com",
		"OAuthToken" => $requestToken
	)
);

//Call the MerchantInitializationApi with required params
$merchantInitializationResponse = MerchantInitializationApi::create($merchantInitializationRequest);

 <!-- url to jquery 1.10.2 -->
 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/
jquery/1.10.2/jquery.min.js"></script>

<!-- url to sandbox MasterPass Lightbox -->
 <script type="text/javascript" src=" https://sandbox.masterpass.com/
lightbox/Switch/integration/MasterPass.client.js "></script>

<!-- url to production MasterPass Lightbox -->
 <!-- <script type="text/javascript" src=" https://masterpass.com/lightbox/
Switch/integration/MasterPass.client.js "></script> -->

<script type="text/javascript" language="Javascript">

MasterPass.client.cardSecurity({
    "requestToken":"insert_request_token_here",                       //required
    "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm", //required
    "merchantCheckoutId":"insert_checkout_id_here",                   //required
    "precheckoutTransactionId":"insert_prechechout_txn_id_here",      //required
    "successCallback": function(mpLightboxResponse){ ... },           //optional
    "failureCallback": function(mpLightboxResponse){ ... },           //optional
    "cancelCallback": function(mpLightboxResponse){ ... }             //optional
});

</script>

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=success

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=cancel

http://www.somemerchant.com/checkoutcomplete.htm
?mpstatus=failure

function handleCallbackSuccess (data) {
    callYourServerWith(data.mpstatus);
}

$expressCheckoutRequest = new ExpressCheckoutRequest();

$expressCheckoutRequest->setMerchantCheckoutId("insert_checkoutId_here");
$expressCheckoutRequest->setPrecheckoutTransactionId("insert_precheckoutTransactionId_here"); // from precheckout data
$expressCheckoutRequest->setCurrencyCode("USD");
$expressCheckoutRequest->setCardId("consumer_selected_cardId");
$expressCheckoutRequest->setOriginUrl("http://www.somemerchant.com");
$expressCheckoutRequest->setAdvancedCheckoutOverride(false);
$expressCheckoutRequest->setOrderAmount("1299");
$expressCheckoutRequest->setDigitalGoods(false);
$expressCheckoutRequest->setShippingAddressId("consumer_selected_shippingAddressId");
$expressCheckoutRequest->setRewardProgramId("consumer_selected_rewardId");

$response = ExpressCheckoutApi::create("insert_longAccessToken_here", $expressCheckoutRequest);

$checkout = response->getCheckout();

$card = $checkout->getCard();
$billingAddress = $card->getBillingAddress();
$contact = $checkout->getContact();
$authOptions = checkout->getAuthenticationOptions(); 
$preCheckoutTransactionId = checkout->getPreCheckoutTransactionId(); 
$rewardProgram = checkout->getRewardProgram(); 
$shippingAddress = checkout->getShippingAddress();
$transactionId = checkout->getTransactionId();
$walletId = checkout->getWalletID();