Masterpass v4

Masterpass is a digital wallet provider that allows payers to store their payment details such as card details, billing and shipping address in a secure server. When paying online the payer can simply log onto Masterpass and select the stored payment details, saving the payer from having to provide their payment details every time they pay online. This is useful if you wish to improve the convenience and user experience plus reduce PCI compliance costs as the wallet provider ensures the security of storing the payer's information.

The Masterpass redirect model is supported by API versions 18 to 30. If you are using API version 31 and above, you must use the Masterpass Lightbox integration.


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 in Merchant Manager.

Masterpass Checkout Experience

This section describes a sample checkout flow for your shop site where the payer uses the shipping address as stored by Masterpass. The payer reviews and confirms the payment on your shop site.

Masterpass Online Flow

The checkout flow is as follows:

  1. A payer browses your shop site, selects one or more products, and clicks Masterpass at the checkout page.
  2. When the payer clicks Masterpass:
    • request a session identifier using the Create Session operation.
    • initiate a Masterpass interaction using the session ID from the Create Session operation in an Open Wallet operation.
    • redirect the payer's browser to Masterpass using the redirect URL returned in the Open Wallet response.
    • Open Wallet API Reference [REST][NVP]

  3. The payer logs in to their Masterpass account using the Masterpass Login page.
  4. The payer selects from the available payment and shipping options. If you are configured in the Mastercard Payment Gateway to collect the shipping address from Masterpass, then Masterpass requests the payer to select a shipping address. The payer may select a shipping address previously stored with Masterpass, or enter a new one. Alternatively, you can collect the shipping address on your shop site before/after redirecting to Masterpass.
  5. When the payer proceeds with the interaction by clicking "Proceed to Checkout" button on the Masterpass website, the Mastercard Payment Gateway redirects the payer from Masterpass back to your shop site using the return URL provided in the Open Wallet request.
    If the payer cancels the interaction at Masterpass, the Mastercard Payment Gateway redirects the payer's browser to the cancel URL provided in the Open Wallet request.
  6. If the interaction was successful, the interaction details and payment details collected at Masterpass are stored in the session identified in the Open Wallet request. At this stage, you can choose to display further pages to the payer or use the session to perform a payment or a storage operation.
    It is recommended that you retrieve the session details using the Retrieve Session operation and check the session contents before you initiate a payment operation.
Masterpass via Hosted Checkout

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

Masterpass via Hosted Payment Session POST

Combining Masterpass and Hosted Payment Session POST integration allows you to collect card details from the payer either via Masterpass or directly via the payment page.

The payment flow is as follows:

  1. Display a payment form to the payer as required for the Hosted Payment Session POST integration. See Hosted Payment Session POST for more details. Your payment form should include a way to identify Masterpass as the checkout option selected by the payer.
  2. When the payer submits the payment form:
    • If the payer has chosen not to pay using Masterpass but instead pay by credit card, then the session will contain the card details directly entered by the payer.
    • If the payer has chosen to pay using Masterpass, then execute the checkout flow as outlined above. When the payment flow successfully completes, the session will contain the payment details.
    • Use the same session created for the Hosted Payment Session integration to store the payment details collected via Masterpass.
  3. You can now initiate a payment or storage operation. Note that card details can be provided using multiple sources of card details.
The submitted payment page for a Masterpass interaction will not contain any card details. Hence, you must ignore validation errors for the missing card details.
Masterpass via Your Own Integration

If your integration already supports Masterpass interaction then you can use the payment details collected via Masterpass to perform a transaction via API. To identify Masterpass as the source of the payment details, you must specify:

  • order.walletProvider: Set this field to MASTERPASS_ONLINE
  • order.walletIndicator: The wallet indicator as returned by Masterpass.

Wallet Provider API Reference [REST][NVP]

Wallet Indicator API Reference [REST][NVP]

User Interface 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.

Configuring your Masterpass Merchant Account

Before using Masterpass as a wallet provider 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, which your payment service provider must use to enable and configure you for Masterpass in Merchant Manager.

Testing Your Integration

Masterpass requests for merchants in 'production' and 'test' (your Merchant ID prefixed with "TEST") mode are routed to the Masterpass Sandbox and Masterpass Emulator respectively. To access the Masterpass Sandbox, please contact your payment service provider.

Masterpass Emulator Details

The Masterpass Emulator allows you to test your integration for using the Masterpass wallet functionality via the Mastercard Payment Gateway.

For your Test Merchant Profile the OPEN_WALLET response returns a redirect URL (wallet.redirectURL) that redirects the payer's browser to the Mastercard Payment Gateway Masterpass Emulator.

The Masterpass Emulator does not require you to enter the payer's Masterpass credentials (user name and password). It provides default test data for all fields, including the card holder name, card number, expiry date, and billing address details. You can override these details with your test details, apart from the card number.

You can only select a card number from the drop down provided. Test card numbers are provided depend the card types you support.

Test Cards Card Number
American Express
Diners Club


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

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.

Do I need to implement the transaction status post back to Masterpass?

No. The Mastercard Payment Gateway will automatically submit the transaction post back to Masterpass after processing the transaction.

Copyright © 2023 Mastercard