Masterpass is a service that enables payers to store, manage and securely share their payment information, shipping and billing address information with the websites and mobile apps they transact with. This is useful if you wish to improve the checkout experience for the payer, and also reduce PCI compliance costs as the wallet provider secures and protects the payer's information.


To use Masterpass via the Mastercard Payment Gateway, your payment service provider must have your merchant profile boarded onto Masterpass. Once you are successfully boarded, you will be issued with a Checkout Identifier that your payment service provider uses to configure you for Masterpass.

Masterpass Standard Checkout

Masterpass Standard Checkout allows the payer to interact with their Masterpass digital wallet without having to leave your web page. The interaction is rendered in a Lightbox displayed over the top of your checkout page.

Masterpass Standard Checkout Flow

The diagram below shows a sample checkout flow for your shop site and Masterpass.

  1. A payer browses your shop site, selects one or more products, and clicks BUY WITH Masterpass on the checkout page.
  2. In the Masterpass Lightbox, displayed over the top of the shop site, the payer:
    • Logs into their Masterpass wallet.
    • Selects a card for payment.
    • Selects a shipping address, or adds a new one.
    • Clicks a button to confirm their choices and closes the Masterpass Lightbox.
  3. At your shop site the payer finalizes the purchase, and you display the order summary/receipt.

Request a Masterpass Standard Checkout Interaction

Masterpass via Hosted Checkout

If you have an existing Hosted Checkout integration, Masterpass will automatically be available once you have successfully enabled it.

If the Masterpass payer interaction includes 3-D Secure authentication then the 3DS authentication results are added to the session.
Masterpass via Direct Payment

If you want full control over the Masterpass Lightbox interaction on your payment page, you can choose this option to invoke the Lightbox yourself.

Masterpass Standard Checkout is supported by API versions 31 and above. If you are using API version 18-30, you must use the Masterpass redirect integration.
Sample JavaScript Code to Invoke the Masterpass Lightbox
<script src=""></script>
<script type="text/javascript">
          "successCallback": onSuccessfulCheckout,
          "cancelCallback": onCancel,
          "failureCallback": onFailure,
          "requestToken": "<wallet.masterpass.requestToken>",
          "merchantCheckoutId": "<wallet.masterpass.merchantCheckoutId>",
          "allowedCardTypes": "<wallet.masterpass.allowedCardTypes>"

    function onSuccessfulCheckout(data) {
    function onCancel() {
        // do something to tell you the cardholder cancelled
    function onFailure() {
        // do something to tell you things have gone wrong
Do not invoke any API operation directly from the browser.
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:

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

    Open Wallet 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. 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.allowedCardTypes

    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. See Advanced Checkout.

    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 Mastercard Payment Gateway. See Perform an Operation Using the Session.

Masterpass Branding Requirements for your Shop Site

You must comply with the user interface branding requirements from Masterpass when you present Masterpass as an option to your payers on your website. For guidelines on how to present the user interface elements in your checkout pages, see Masterpass Branding.

Masterpass Pairing

Masterpass pairing is the process of linking a payer's Masterpass Wallet account with their account on your shop site/app. For more information, see Masterpass Pairing.

Advanced Checkout

If you have set up Advanced Checkout payer authentication services with Masterpass, then 3-D Secure (3DS) authentication will be facilitated by Masterpass's MPI.

The results of the 3DS authentication will be added to the session and returned in the Update Session From Wallet response. It's recommended that your integration verifies the 3DS results in the session before proceeding to submit the payment to the Mastercard Payment Gateway.

3DS may be opted into for Mastercard, Maestro, and Visa cards only.

Testing Your Integration

If your Merchant ID is prefixed with "TEST", requests are routed to the Masterpass Sandbox.

For testing purposes, ensure that references to the MasterPass.client.js library are set to

To perform an end-to-end testing of your Masterpass integration, including the 3DS interaction, add the following test cards to your payer's wallet in the Masterpass sandbox. You can provide any expiry date or CSC.

Test Cards Card Number 3D Secure Enrolled
5506900140100305 Y
5506900140100107 Y
5506900140100503 N
4440000009900010 Y
4440000042200014 Y
4440000042200022 N
American Express
340000099900036 Y
  340000099900028 Y
  340000099900044 Y
  340000099900051 N
Diners Club
30599900026332 Y
30599900026340 N
Discover 6011100099900534 -
6011100099900013 -


How do I ensure that payers can only select from card types that my merchant profile supports?

If the payer's Masterpass Wallet is not paired with your business, the Mastercard Payment Gateway retrieves the supported card types from your merchant configuration and ensures that only these card types are available for selection at Masterpass.

If the payer's Masterpass Wallet is paired with your business, the card types are retrieved from the payer's Masterpass wallet.

Copyright © 2023 Mastercard