Masterpass Pairing

Masterpass pairing is the process of linking a payer's Masterpass Wallet account with their account on your shop site/app. Once a payer consents to pairing, you can retrieve non-sensitive, pre-checkout payment data stored in the payer's wallet and present it to the payer during checkout. The data includes:

  • Cards in wallet (without the actual card number).
  • Shipping addresses.
  • Customer information.
  • Rewards data (currently not supported on CommWeb payment gateway)

Pairing is facilitated by a Long Access Token (LAT), a one-time use token, provided by the gateway for Masterpass paired accounts. Each time a call using LAT is made, a new LAT will be passed back to you. This new LAT will then need to be stored, to be used the next time.

Pairing is currently supported on the CommWeb payment gateway for DirectAPI integration only.
Request Pairing

You can offer Masterpass Connected Checkout to the payer on your site/app either during checkout or outside of a checkout.

Request Pairing Outside of a Checkout

You can request consent for pairing from the payer outside of a checkout experience (for example, during sign-up or account management). The pairing process starts when a payer clicks the 'Connect with Masterpass' button on your site/app.

Sample JavaScript Code for Stand-Alone Pairing
<script src="https://masterpass.com/lightbox/Switch/integration/MasterPass.client.js"></script>
<script type="text/javascript">
     // INITIALIZE and INVOKE THE MASTERPASS LIGHTBOX FOR STANDALONE PAIRING
    MasterPass.client.connect({
        "requestedDataTypes": "[ADDRESS, PROFILE,CARD]",
        "requestPairing: "true",
        "version":"v6",
        "successCallback": onSuccessfulCheckout,
        "cancelCallback": onCancel,
        "failureCallback": onFailure,
        // USE PARAMETERS FROM THE OPEN WALLET RESPONSE
        "requestToken": "<wallet.masterpass.requestToken>",
        "pairingToken": "<wallet.masterpass.pairingRequestToken>",
        "merchantCheckoutId": "<wallet.masterpass.merchantCheckoutId>"
     });
     // RETRIEVE PARAMETERS FROM THE LIGHTBOX INTERACTION
    function onSuccessfulCheckout(data) {
       document.getElementById('oauthToken').value=data.oauth_token;
       document.getElementById('oauthVerifier').value=data.oauth_verifier;
       document.getElementById('checkoutUrl').value=data.checkout_resource_url;
       document.getElementById('pairingToken').value=data.pairing_token;
       document.getElementById('pairingVerifier').value=data.pairing_verifier;
     }
    function onCancel() {
        // do something to tell you the cardholder cancelled
      }
     function onFailure() { 
        // do something to tell you things have gone wrong
     }
</script>
  1. Perform a Pair With Wallet operation using order.walletProvider=MASTERPASS_ONLINE
  2. Provide wallet.masterpass.pairingRequestToken returned in the Pair With Wallet response to invoke the Masterpass Lightbox (using MasterPass.client.connect( ) method).

The Masterpass Lightbox will present the pairing offer to the payer. If the payer consents, pairing is established and you can retrieve the payer's pre-checked out data when the payer returns to your site/app for a checkout.

Request Pairing During Checkout

You can request consent for pairing from the payer during a checkout interaction with Masterpass. The pairing process starts when a payer clicks the 'Buy with Masterpass' button on your site/app.

Sample JavaScript Code to Invoke the Masterpass Lightbox with Pairing During Checkout
<script src="https://masterpass.com/lightbox/Switch/integration/MasterPass.client.js"></script>
<script type="text/javascript">
    // INITIALIZE AND INVOKE THE MASTERPASS LIGHTBOX FOR CHECKOUT AND PAIRING
    MasterPass.client.checkout({
          "requestedDataTypes": "[ADDRESS, PROFILE,CARD]",
          "requestPairing: "true",
          "version":"v6",
          "successCallback": onSuccessfulCheckout,
          "cancelCallback": onCancel,
          "failureCallback": onFailure,
          // USE PARAMETERS FROM THE OPEN WALLET RESPONSE
          "requestToken": "<wallet.masterpass.requestToken>",
          "pairingToken": "<wallet.masterpass.pairingRequestToken>",
          "merchantCheckoutId": "<wallet.masterpass.merchantCheckoutId>",
          "allowedCardTypes": "<wallet.masterpass.allowedCardTypes>"
    });
    // RETRIEVE PARAMETERS FROM THE LIGHTBOX INTERACTION
    function onSuccessfulCheckout(data) {
         document.getElementById('oauthToken').value=data.oauth_token;
         document.getElementById('oauthVerifier').value=data.oauth_verifier;
         document.getElementById('checkoutUrl').value=data.checkout_resource_url;
         document.getElementById('pairingToken').value=data.pairing_token;
         document.getElementById('pairingVerifier').value=data.pairing_verifier;
    }
    function onCancel() {
         // do something to tell you the cardholder cancelled
    }
    function onFailure() {
         // do something to tell you things have gone wrong
    }
 </script>
  1. Perform Pair With Wallet and Open Wallet operations using order.walletProvider=MASTERPASS_ONLINE
  2. Use the parameters from their responses (specifically wallet.masterpass.pairingRequestToken from Pair With Wallet) to invoke the Masterpass Lightbox.

The Masterpass Standard Checkout interaction will display to the payer. After the payer has selected the payment details, the pairing offer will be presented to the payer. If the payer consents, pairing is established and you can retrieve the payer's pre-checked out data when the payer returns to your site/app for a checkout.

Pair With Wallet API Reference [REST][NVP]

For Express Checkout, set the flag requestExpressCheckout to true when invoking the Masterpass Lightbox.
Get Pairing Result

When the Masterpass Lightbox closes and returns control to your shop site, you can obtain the result of your pairing request using the data from the callback. For more information on handling callbacks, see Masterpass Documentation.

  1. Retrieve the following parameters from the callback URL or the success callback method (returned only if the pairing was successful):
    • wallet.masterpass.pairingToken
    • wallet.masterpass.pairingVerifier
    If the pairing was unsuccessful, you cannot use Masterpass Connected Checkout/Masterpass Express Checkout for this payer; though you may offer pairing to the payer again during a future interaction (during checkout or outside a checkout).
  2. Perform a Retrieve Wallet Pairing Result operation using the retrieved parameters from the callback URL. This will return a Long Access Token (LAT) in wallet.masterpass.longAccessToken.
    You must save this for the next Masterpass Connected Checkout interaction with this payer. The LAT is consumed after every interaction, and you must save the new one before every subsequent interaction.

Retrieve Wallet Pairing Result API Reference [REST][NVP]

Unpairing

A payer can unpair their Masterpass wallet from their account at your shop site/app at any time, using Masterpass account management. This will prevent you from accessing the payer's wallet information; however, you can request pairing again.

Masterpass Checkout Experience Using Pairing

Masterpass offers two checkout experiences to payers using a paired wallet.

Data shared in connection with Masterpass Connected Checkout/Masterpass Express Checkout may only be used to implement checkout and must be destroyed immediately after checkout is complete.
Masterpass Connected Checkout

Masterpass Connected Checkout allows you to provide a seamless, customized checkout experience to your payer. Payers who have paired their wallet with you have non-sensitive pre-checkout payment data available for selection before checkout without the payer having to log into their Masterpass wallet. The payer can complete their checkout by simply entering the wallet password at Masterpass.

Sample JavaScript Code to Invoke the Masterpass Lightbox During Return Connected Checkout
<script src="https://masterpass.com/lightbox/Switch/integration/MasterPass.client.js"></script>
<script type="text/javascript">
    // INITIALIZE AND INVOKE THE MASTERPASS LIGHTBOX DURING CONNECTED CHECKOUT
    MasterPass.client.checkout({
         "version":"v6",
         "successCallback": onSuccessfulCheckout,
         "cancelCallback": onCancel,
         "failureCallback": onFailure,
         // USE PARAMETERS FROM THE OPEN WALLET RESPONSE
         "requestToken": "<wallet.masterpass.requestToken>",
         "merchantCheckoutId": "<wallet.masterpass.merchantCheckoutId>",
         "cardId": "<wallet.masterpass.precheckoutData.card.masterpassCardId>",
         "shippingId": "<wallet.masterpass.precheckoutData.shippingAddress[<index of selected shipping address>].address.masterpassShippingId>",
         "precheckoutTransactionId": "<wallet.masterpass.precheckoutData.precheckoutTransactionId>",
         "walletName": "<wallet.masterpass.precheckoutData.walletName>",
         "consumerWalletId": "<wallet.masterpass.precheckoutData.consumerWalletId>"
     });
     // RETRIEVE PARAMETERS FROM THE LIGHTBOX INTERACTION
    function onSuccessfulCheckout(data) {
        document.getElementById('oauthToken').value=data.oauth_token;
        document.getElementById('oauthVerifier').value=data.oauth_verifier;
        document.getElementById('checkoutUrl').value=data.checkout_resource_url;
     }
    function onCancel() {
        // do something to tell you the cardholder cancelled
    }
    function onFailure() {
        // do something to tell you things have gone wrong
    }
</script>
On your Web Server: Create a Session and Initiate a Wallet Interaction
  1. Perform a Create Session operation to obtain a session ID.

    Create Session API Reference[REST][NVP]

  2. Use the session ID from the Create Session response in an Open Wallet operation to obtain the data required to invoke the Masterpass Lightbox. You need to provide the following in the Open Wallet operation:

    • wallet.masterpass.originUrl: The URL of the page that invoked the Masterpass Lightbox.
    • order.amount: The amount of the order.
    • order.currency: The currency in which the order is being paid.

    Open Wallet API Reference [REST][NVP]

  3. A payer with a paired wallet logs into your shop site/app. Before presenting the checkout interface, perform a Retrieve Wallet Options operation to get the payer's wallet data for display on your payment page. Use the latest Long Access Token (LAT) provided by the gateway for the Masterpass paired account in the operation.

    The Retrieve Wallet Options response includes a new LAT in wallet.masterpass.longAccessToken. You must save this for the next interaction.

    Retrieve Wallet Options API Reference [REST][NVP]

In your Payment Page: Initialize and Invoke the Masterpass Lightbox
  1. Reference MasterPass.client.js JavaScript client library in your payment page.

  2. After the shopping experience, present the payer with an interface that allows them to select their payment and shipping options retrieved from the wallet. When the payer clicks BUY WITH Masterpass, invoke the Masterpass Lightbox using the following parameters from the Open Wallet response.

    • wallet.masterpass.requestToken
    • wallet.masterpass.merchantCheckoutId
    • wallet.masterpass.precheckoutData.card.masterpassCardId
    • wallet.masterpass.precheckoutData.shippingAddress[<index of selected shipping address>].address.masterpassShippingId
    • wallet.masterpass.precheckoutData.precheckoutTransactionId
    • wallet.masterpass.precheckoutData.walletName
    • wallet.masterpass.precheckoutData.consumerWalletId

    You must provide a callback URL and/or callback methods to manage the response from the Masterpass Lightbox interaction. For more information on handling callbacks, see Masterpass Documentation.

  3. Retrieve the following parameters (returned only if the Masterpass Lightbox interaction was successful) from the callback URL or a success callback method, and pass them to your web server.

    • oauth_token
    • oauth_verifier
    • checkout_resource_url
On your Web Server: Collect Payment Details into a Session
  1. Perform an Update Session From Wallet operation to get the payer's payment and shipping details from Masterpass. You need to provide the following parameters in this operation.

    • Session ID: The identifier for the payment session as returned by the Create Session operation.
    • order.walletProvider: Set this to MASTERPASS_ONLINE.
    • wallet.masterpass.oauthToken: The oauth_token retrieved from the callback.
    • wallet.masterpass.oauthVerifier: The oauth_verifier retrieved from the callback.
    • wallet.masterpass.checkoutUrl: The checkout_resource_url retrieved from the callback.

    If successful, the returned session will contain the payer's payment details from the Masterpass interaction.

    If the Masterpass payer interaction includes 3-D Secure authentication then the 3DS authentication results are added to the session and returned in the Update Session From Wallet response.

    Update Session From Wallet API Reference [REST][NVP]

  2. Use the returned session to present an order confirmation page or to submit a payment to the CommWeb payment gateway. See Perform an Operation Using the Session.
Masterpass Express Checkout

Masterpass Express Checkout offers the same checkout experience as Masterpass Connnected Checkout but much faster. Payers who have paired their wallet with you can complete their checkout without logging in to their Masterpass wallet.

Only select merchants who pass the vetting specifications at Masterpass are eligible to integrate with Express Checkout. For more information, contact Commonwealth Bank of Australia.
On your Web Server: Create a Session and Retrieve Pre-Checkout Data
  1. Perform a Create Session operation to obtain a session ID.

    Create Session API Reference[REST][NVP]

  2. Perform a Retrieve Wallet Options operation to get the payer's wallet data for display on your payment page. Use the latest Long Access Token (LAT) provided by the gateway for the Masterpass paired account in the operation.

    The Retrieve Wallet Options response includes:

    • a new LAT in wallet.masterpass.longAccessToken. You must save this for the next interaction.
    • a pre-checkout transaction ID in wallet.masterpass.precheckoutData.precheckoutTransactionId. This identifies the checkout data retrieved from the payer's wallet.

    Retrieve Wallet Options API Reference [REST][NVP]

In your Payment Page: Authenticate Payer and Present Pre-Checkout Data to the Payer
  1. A payer with a paired wallet logs into your shop site/app.
  2. After the shopping experience, present the payer with an interface that allows them to select their payment and shipping options retrieved from the wallet.
On your Web Server: Collect Payment Details into a Session
  1. When the payer clicks BUY WITH Masterpass, perform an Update Session From Wallet operation to get the payer's payment and shipping details from Masterpass. You need to provide the following parameters in this operation.

    • Session ID: The identifier for the payment session as returned by the Create Session operation.
    • order.walletProvider(set to MASTERPASS_ONLINE)
    • wallet.masterpassExpressCheckout.longAccessToken
    • wallet.masterpassExpressCheckout.masterpassCardId
    • wallet.masterpassExpressCheckout.masterpassShippingId
    • wallet.masterpassExpressCheckout.originUrl
    • wallet.masterpassExpressCheckout.precheckoutTransactionId
    • wallet.masterpassExpressCheckout.secondaryOriginUrl

    If successful, the returned session will contain the payer's payment details from the Masterpass interaction.

    Update Session From Wallet API Reference [REST][NVP]

  2. If Update Session From Wallet request returns wallet.masterpass.payerAuthentication=REQUIRED, you need to invoke the Card Security UI to perform advanced authentication (for example, 3DS) for the transaction. For information, see the Card Security UI section.

    Once the advanced authentication is complete, perform Update Session From Wallet again.

  3. Use the returned session to present an order confirmation page or to submit a payment to the CommWeb payment gateway. See Perform an Operation Using the Session.

Copyright © 2023 Commonwealth Bank of Australia