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 Mastercard 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.
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>
- Perform a
Pair With Walletoperation usingorder.walletProvider=MASTERPASS_ONLINE - Provide
wallet.masterpass.pairingRequestTokenreturned in thePair With Walletresponse to invoke the Masterpass Lightbox (usingMasterPass.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>
- Perform
Pair With WalletandOpen Walletoperations usingorder.walletProvider=MASTERPASS_ONLINE - Use the parameters from their responses (specifically
wallet.masterpass.pairingRequestTokenfromPair 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.
- Retrieve the following parameters from the callback URL or the success callback method (returned only if the pairing was successful):
wallet.masterpass.pairingTokenwallet.masterpass.pairingVerifier
- Perform a
Retrieve Wallet Pairing Resultoperation using the retrieved parameters from the callback URL. This will return a Long Access Token (LAT) inwallet.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.
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.
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>
- Perform a
Create Sessionoperation to obtain a session ID. - Use the session ID from the
Create Sessionresponse in anOpen Walletoperation to obtain the data required to invoke the Masterpass Lightbox. You need to provide the following in theOpen Walletoperation:
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.
- A payer with a paired wallet logs into your shop site/app. Before presenting the checkout interface, perform a
Retrieve Wallet Optionsoperation 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 Optionsresponse includes a new LAT inwallet.masterpass.longAccessToken. You must save this for the next interaction.
- Reference
MasterPass.client.jsJavaScript client library in your payment page.- For testing:
https://sandbox.masterpass.com/lightbox/Switch/integration/MasterPass.client.js. - For live transactions:
https://masterpass.com/lightbox/Switch/integration/MasterPass.client.js.
- For testing:
-
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 Walletresponse.wallet.masterpass.requestTokenwallet.masterpass.merchantCheckoutIdwallet.masterpass.precheckoutData.card.masterpassCardIdwallet.masterpass.precheckoutData.shippingAddress[<index of selected shipping address>].address.masterpassShippingIdwallet.masterpass.precheckoutData.precheckoutTransactionIdwallet.masterpass.precheckoutData.walletNamewallet.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_tokenoauth_verifiercheckout_resource_url
- Perform an
Update Session From Walletoperation 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 Sessionoperation. order.walletProvider: Set this toMASTERPASS_ONLINE.wallet.masterpass.oauthToken: Theoauth_tokenretrieved from the callback.wallet.masterpass.oauthVerifier: Theoauth_verifierretrieved from the callback.wallet.masterpass.checkoutUrl: Thecheckout_resource_urlretrieved 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 theUpdate Session From Walletresponse. - Session ID: The identifier for the payment session as returned by the
- Use the returned session to present an order confirmation page or to submit a payment to the Mastercard Gateway. See Perform an Operation Using the Session.
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.
- Perform a
Create Sessionoperation to obtain a session ID. - Perform a
Retrieve Wallet Optionsoperation 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 Optionsresponse 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.
- a new LAT in
- A payer with a paired wallet logs into your shop site/app.
- 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, perform an
Update Session From Walletoperation 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 Sessionoperation. order.walletProvider(set toMASTERPASS_ONLINE)wallet.masterpassExpressCheckout.longAccessTokenwallet.masterpassExpressCheckout.masterpassCardIdwallet.masterpassExpressCheckout.masterpassShippingIdwallet.masterpassExpressCheckout.originUrlwallet.masterpassExpressCheckout.precheckoutTransactionIdwallet.masterpassExpressCheckout.secondaryOriginUrl
If successful, the returned session will contain the payer's payment details from the Masterpass interaction.
- Session ID: The identifier for the payment session as returned by the
- If
Update Session From Walletrequest returnswallet.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 Walletagain. - Use the returned session to present an order confirmation page or to submit a payment to the Mastercard Gateway. See Perform an Operation Using the Session.