Masterpass (now Click to Pay in the United States) is a digital wallet that securely stores a shopper's payment and shipping details. It supports all major credit and debit card types, including Mastercard, Visa, American Express, Discover, Diners, and JCB. You may wish to offer Masterpass in order to increase conversions across devices, including mobile devices.

📘

Note:

Masterpass is supported for both first time transactions & recurring transactions. Please review the highlighted sections for detailed information.

The Masterpass payment method is automatically available to you with the Payment API.

The shopper experience with Masterpass

Masterpass and Click to Pay in the United States

Masterpass in the United States is changing to Click to Pay. For more information, refer to Click to Pay Checkout.

Supported Markets

Masterpass is available for merchants in the following countries.

Items purchased with Masterpass can be shipped to any country, as long as that country is not listed on the U.S. Department of Treasury Office of Foreign Assets Control (OFAC) sanctioned list. For more information, click here.

Implementing Masterpass via the API

These steps describe how to implement Masterpass in either the Payment API or Extended Payment API:

• Step 1: Add the Masterpass button to your checkout form
• Step 2: Send the Create Wallet request to receive fields for the Masterpass lightbox
• Step 3: Add scripts and call the handleBuyWithMasterpass JS function
• Step 4: Shopper completes Masterpass step
• Step 5: Get the wallet ID and retrieve wallet details
• Step 6: Get final shopper confirmation
• Step 7: Process the transaction:
  • In the Payment API
  • In the Extended Payment API

Step 1: Add the Masterpass button to your checkout form

Add the Masterpass button to your checkout form, as shown in the example below. For a full list of Masterpass buttons, see this document.

📘

Upon implementing Masterpass, please comply with the Masterpass branding requirements.

<div id="checkoutButtonDiv" onClick="createWallet();">
  <a href="#"> 
    <img src="https://static.masterpass.com/dyn/img/btn/global/mp_chk_btn_126x030px.svg" alt="Buy with Masterpass">
  </a>
</div>

Step 2: Send the Create Wallet request to receive fields for the Masterpass lightbox

When the shopper clicks the Masterpass button, you will need to provide some parameters and get the fields required to launch the Masterpass lightbox.

To do this, send a Create Wallet request with the wallet type set to MASTERPASS, and include the originUrl and returnUrl. For more information, see the wallet resource.

This request should be sent to: services/2/wallets

Following is a sample Create Wallet request:

{
    "walletType": "MASTERPASS",
    "originUrl": "http://www.originURL.com",
    "returnUrl": "http://www.returnURL.com"
}

Upon success, you will receive a response similar to the following, with the walletToken, merchantCheckoutId, and allowedCardTypes:

{
    "allowedCardTypes": "master,amex,diners,discover,visa",
    "walletType": "MASTERPASS",
    "merchantCheckoutId": "a4a6w4vkqzjnzikhr6ihj1ikqnlqhu5ymb",
    "walletToken": "f9babd23df00acc9b049ac4694d2344f8f73f4e8"
}

Step 3: Add scripts and call the handleBuyWithMasterPass JS function

Put the scripts below in the header of your checkout form page. When you receive the response to your Create Wallet request, add the fields from the response into the handleBuyWithMasterPass JS function and then call the function.

<meta http-equiv="Content-Type"	content="text/html; charset=windows-1255">
<script type="text/javascript" src="Scripts/jquery-1.5.1.js"></script>
<script type="text/javascript" src="https://sandbox.masterpass.com/lightbox/Switch/integration/MasterPass.client.js"></script>
<script>
	function handleBuyWithMasterPass() {
		MasterPass.client.checkout({
			"requestToken" : "${data.requestToken}",
"callbackUrl" : "https://sandbox.bluesnap.com/services/WalletCallbackServlet?wallet_type=MASTERPASS",
			"merchantCheckoutId" : "${data.merchantCheckoutId}",
			"allowedCardTypes" : "${data.allowedCardTypes}",
			"version" : "v6"
		});
	}
</script>

Fields:

• requestToken: Insert the wallet token
• callbackUrl: For Sandbox, use the URL shown in the example above. For Production, use https://ws.bluesnap.com/services/WalletCallbackServlet?wallet_type=MASTERPASS
• merchantCheckoutId: Insert the merchant checkout ID
• allowedCardTypes: Insert the allowed card types
• version: Use the version shown in the example above

📘

Note:

In production, the Masterpass URL should be changed to: https://www.masterpass.com/lightbox/Switch/integration/MasterPass.client.js**

Step 4: Shopper completes Masterpass step

Once you call the handleBuyWithMasterPass JS function, the Masterpass lightbox opens. The shopper logs in to Masterpass or creates a new Masterpass account. The shopper then confirms payment, billing and shipping info, and clicks Finish Shopping upon completion.

Step 5: Get the wallet ID and retrieve wallet details

When the shopper completes the Masterpass step, the browser is redirected to your return URL (that you specified in Step 2). The request includes an operation=success/failure/cancel parameter, to indicate whether the transaction was successful in Masterpass.

If operation=success, BlueSnap sends the wallet ID. For example:

https://www.merchant.com/WalletServlet?operation=success&walletId=546

Make sure to obtain this wallet ID, as you will need it to complete the rest of the process.

If operation=failure, BlueSnap sends the error name, code, and description. For example:

https://www.merchant.com/WalletServlet?operation=failure&errorName=WALLET_PROCESSING_FAILURE&code=23003&description=Wallet processor is currently unavailable, please try again later

If operation=cancel, BlueSnap sends the below error name, code and description:

https://www.merchant.com/WalletServlet?operation=cancel&errorName=WALLET_CHECKOUT_CANCELED&code=23014&description=Customer canceled the wallet checkout flow without completing the purchase

Step 6: Get final shopper confirmation

If the shopper has successfully completed the Masterpass step, send a Retrieve Wallet request to get the wallet details, including the shopper's information.

This request should be sent to: services/2/wallets/{walletId}

Insert the ID of the wallet in the request URL. For example:
services/2/wallets/546

In the response, you will receive the wallet resource with the shopper's payment, shipping and billing info. For more information, see the wallet resource.

Redirect the shopper to a confirmation page and display the information from the wallet, in order to get the shopper's final approval for the purchase and payment.

Step 7: Process the transaction

Once you have the shopper's final approval, you are ready to process the transaction. Follow the steps below for the Payment API or the Extended Payment API.

In the Payment API

There are two different ways to do this:

Option 1. Create or update a Vaulted Shopper with the wallet info, and then use the vaulted shopper ID in the Auth Capture or Auth Only request

You can save the shopper's information from the wallet by including it in a Create Vaulted Shopper or Update Vaulted Shopper request.

Then just send a standard Auth Only or Auth Capture request with the vaulted shopper ID.

Option 2. Add the wallet ID directly in your Auth Capture or Auth Only request

You can instead include the wallet ID directly in an Auth Only or Auth Capture request.

For example:

{
    "walletId": 21,
    "amount": 35,
    "currency": "USD",
    "cardTransactionType": "AUTH_CAPTURE"
}

In the Extended Payment API

There are two different ways to do this:

Option 1. Create or update a Shopper with the wallet info, and then use the shopper ID in the Create Order with Existing Shopper or Create Shopping Context request

You can save the shopper's information from the wallet by including it in a Create Shopper or Update Shopper request.

For example:

<shopper xmlns="http://ws.plimus.com">
  <web-info>
    <ip>62.219.121.253</ip>
  </web-info>
  <shopper-info>
    <store-id>11580</store-id>
    <shopper-currency>USD</shopper-currency>
  </shopper-info>
  <wallet-id>21</wallet-id>
</shopper>

Then just send a standard Create Order with Existing Shopper or Create Shopping Context request with the shopper ID.

Option 2. Add the wallet ID directly in Create Order and New Shopper request

You can instead include the wallet ID directly in a Create Order and New Shopper request.

For example:

<batch-order xmlns="http://ws.plimus.com">
  <shopper xmlns="http://ws.plimus.com">
    <web-info>
     <ip>62.219.121.253</ip>
    </web-info>
    <shopper-info>
      <store-id>11580</store-id>
      <shopper-currency>USD</shopper-currency>
    </shopper-info>
    <wallet-id>21</wallet-id>
  </shopper>
  <order>
    <ordering-shopper>
        <web-info>
        <ip>62.219.121.253</ip>
        <remote-host>www.merchant.com</remote-host>
        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
      </web-info>
    </ordering-shopper>
    <cart>
      <cart-item>
        <sku>
        <sku-id>2183716</sku-id>
        </sku>
        <quantity>1</quantity>
      </cart-item>
    </cart>
    <expected-total-price>
      <amount>10</amount>
      <currency>USD</currency>
    </expected-total-price>
  </order>
</batch-order>

Masterpass Sandbox Testing

To test the Masterpass flow, you'll need a test Masterpass account with a test card added. You may use the following card:
ccn: 5506900140100305
cvv: Any
exp: Any

For complete details, see Masterpass Testing.

Back to Top