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:
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.
You can offer Masterpass Connected Checkout to the payer on your site/app either during checkout or 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.
<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>
Pair With Wallet
operation using order.walletProvider=MASTERPASS_ONLINE
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.
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.
<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>
Pair With Wallet
and Open Wallet
operations using order.walletProvider=MASTERPASS_ONLINE
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]
requestExpressCheckout
to true
when invoking the Masterpass Lightbox.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.
wallet.masterpass.pairingToken
wallet.masterpass.pairingVerifier
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
. 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 offers two checkout experiences to payers using a paired wallet.
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.
<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>
Create Session
operation to obtain a session ID.
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.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.
MasterPass.client.js
JavaScript client library in your payment page.
https://sandbox.masterpass.com/lightbox/Switch/integration/MasterPass.client.js
.https://masterpass.com/lightbox/Switch/integration/MasterPass.client.js
.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.
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
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. 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.
Update Session From Wallet
response.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.
Create Session
operation to obtain a session ID.
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:
wallet.masterpass.longAccessToken
. You must save this for the next interaction.wallet.masterpass.precheckoutData.precheckoutTransactionId
. This identifies the checkout data retrieved from the payer's wallet.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. 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
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.
Copyright © 2023 Suncorp