Masterpass Guide

    Accept payments via Masterpass in your existing Stripe integration.

    Masterpass is a third-party service that stores payment and shipping information for its users in order to streamline the checkout process. Instead of entering payment information on your checkout page, users can click the Masterpass button instead. Your Stripe integration receives a unique transaction ID that it can use to create a charge against the payment information stored in the user’s Masterpass account.

    Integrating the Masterpass button

    To get started, generate your Masterpass Checkout ID in the Dashboard and configure your sandbox and production callback URLs.

    To use Masterpass on your website, add the following script tag to your HTML document:

    <script type="text/javascript" src="https://sandbox.masterpass.com/integration/merchant.js"></script>
    <script type="text/javascript" src="https://masterpass.com/integration/merchant.js"></script>

    To display the Masterpass button, use the following image:

    <img id="mpbutton" src="https://static.masterpass.com/dyn/img/btn/global/mp_chk_btn_147x034px.svg"/>
    

    Attach a click handler to the image and use it to invoke the masterpass.checkout function with the desired parameters:

    const button = document.getElementById('mpbutton');
    
    button.addEventListener('click', (ev) =>
      masterpass.checkout({
        checkoutId: '{{MASTERPASS_CHECKOUT_ID}}',
        allowedCardTypes: ['master', 'amex', 'visa'],
        amount: '10.00',
        currency: 'USD',
        cartId: '{{UNIQUE_ID}}',
        callbackUrl: '{{CALLBACK_URL}}'
      }));
    

    The masterpass.checkout function requires the following parameters:

    Parameter Description
    checkoutId The Checkout ID for your Masterpass project, copied from the Dashboard
    allowedCardTypes A list of the Masterpass-compatible payment providers that you want to support
    amount The amount of the transaction, expressed in decimal format
    currency The currency in which to perform the transaction
    cartId A unique string that you generate to identify the purchase
    callbackUrl This optional parameter can be used to override the default callbackUrl configured when activating Masterpass.

    For more details about the masterpass.checkout function and the parameters that it accepts, refer to Mastercard’s documentation.

    Completing the payment

    When the user clicks the Masterpass button on your checkout page, it takes them to the Masterpass website where they can select an existing payment method from their account or input a new one. When the user completes the process, Masterpass redirects them to the callback URL that you configured when activating Masterpass, or the specified callback URL when invoking masterpass.checkout function. It appends an oauth_verifier URL query parameter that your application can use to complete the transaction.

    In the route handler for the redirect destination, extract the URL query parameter and use it to create a source. Next, create a charge with the ID of the returned source. The following code example demonstrates how to create a Masterpass charge in Node.js with the Koa framework:

    router.get('/callback', async (ctx) => {
      const amount = 1000;
      const currency = 'usd';
    
      const result = await stripe.sources.create({
        type: 'card', currency, amount,
        card: {
          masterpass: {
            cart_id: '{{UNIQUE_ID}}',
            transaction_id: ctx.query.oauth_verifier
          }
        }
      });
    
      const charge = await stripe.charges.create({
        amount, currency,
        source: result.source.id
      });
    
      ctx.body = '<h1>Charge succeeded</h1>';
    });
    

    In the route handler for the redirect destination, extract the URL query parameter and use it to confirm the PaymentIntent that you have created at the beginning of the checkout flow. See Using Payment Intents on Web to learn how to manage your checkout flow using Payment Intents.

    The following code example demonstrates how to confirm a PaymentIntent with Masterpass in Node.js with the Koa framework:

    router.get('/callback', async (ctx) => {
      // retrieve the PaymentIntent ID created at the beginner of the checkout flow.
      const payment_intent_id = '{{PAYMENT_INTENT_ID}}';
    
      const payment_intent = await stripe.paymentIntents.confirm(payment_intent_id, {
        payment_method_data: {
          type: 'card',
          card: {
            masterpass: {
              card_id: '{{UNIQUE_ID}}',
              transaction_id: ctx.query.oauth_verifier,
            },
          },
        },
      });
    
      ctx.body = '<h1>Charge succeeded</h1>';
    });
    

    Please use the Masterpass sandbox environment in Stripe’s test mode, and the Masterpass production environment in Stripe’s live mode. When creating the source, be sure to use the same unique value for the cart_id property that you used on your checkout page.

    Testing Masterpass

    To test your Masterpass integration against Mastercard’s sandbox, create a new Masterpass user account during the checkout process on your website. Configure the account to use one of the test cards from the Masterpass documentation. Complete the checkout process as normal, selecting the test card as your Masterpass payment method. If everything worked correctly, Masterpass will redirect you back to your application, which should create the charge as expected.

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    On this page