Masterpass Integration for Wirecard Checkout Seamless

Masterpass Integration for Wirecard Checkout Seamless

Masterpass can be seamlessly integrated into your online shop providing additional convenience to your consumer. In the following chapter we provide information to help understand the payment process and the seamless integration possibilities allowing cross- and up-selling. Masterpass provides a convenient checkout by collecting all information from your consumer in one step, facilitating a simple express and guest checkout.

Payment process with Masterpass

Integration is carried out via a Masterpass button which can be placed anywhere in the online shop.

Your consumer clicks this button and is presented with the Masterpass wallet. In this wallet your consumer selects a credit card and shipping address and reviews the shopping basket. Back at the online shop your consumer can review the order and authorize payment.

When creating the Masterpass button information about the shopping basket content and the total purchase amount needs to be sent to the Wirecard Checkout Server. At this point you can also decide whether you want to restrict or suppress the selection of a shipping address.

After your consumer has selected a credit card and a shipping address this information can be accessed by the online shop. All data that are required for payment can be retrieved by Wirecard which in turn processes the payment on request.

Integration details

To integrate Masterpass into your online shop we provide a REST API for communication between your online shop and the Wirecard Checkout Server. The API is used for all Masterpass specific communication.

In general, the process includes the following steps:

For a graphical overview see the following graphic. Each step will be described in detailed below.


Authorizing with Wirecard

Masterpass related requests with the Wirecard Checkout Server need to be authenticated. You need to authorize using OAuth 2.0 as authentication method. After sending a valid authorization request an access token will be returned which allows you to access resources on the Wirecard Checkout Server. This access token has a finite lifetime, i.e. the token remains valid only for 30 minutes after creation. Once this time has elapsed you need to request a new token. Therefore it is recommended to generally request a new token for each request.

Requesting shipping profiles

Your consumer usually selects a card and a shipping address in the Masterpass wallet. You can define shipping profiles for the items you sell in your online shop. These profiles allow to define geographic restrictions which are applied to the addresses in the Masterpass wallet of your consumer. Thus only those shipping addresses are shown to your consumer you actually ship items to.

During your consumer’s checkout process you can retrieve the available shipping profiles and select the profile applicable to the items your consumer has put into the shopping basket. You may then forward this profile to the Wirecard Checkout Server which in turn will forward the information to Masterpass. Addresses which are not compatible with the shipping profile you selected will not be available to choose from in your consumer’s Masterpass wallet.

You can furthermore decide whether your consumer needs to provide a shipping address or does not need to provide a shipping address (for example, when the consumer purchases only digital goods). For this purpose, the parameter suppressShippingAddressEnable is used.

For our preset shipping profiles or additional specific profiles, contact our support teams.

Creating a Masterpass wallet resource

In order to start the checkout process, a Masterpass wallet resource needs to be created. This wallet resource is needed for information transfer between your online shop and Masterpass, e.g. to send the amount you want to bill your consumer on your side and the selected card, shipping address and billing address on the side of Masterpass.

You can display the shopping basket to your consumer, by storing the relevant shopping basket information in the wallet resource. For your consumers convenience you can also include images of each item.

The amount given in the shopping basket should exclude shipping costs, since this wallet resource is created before your consumer selects the shipping address. The total amount should be calculated after the interaction between your consumer and Masterpass, once the shipping address is known, and has then to be confirmed by your consumer.

Creating a Masterpass button

To offer Masterpass in your online shop, a Masterpass button needs to be integrated into your shop. When your consumer clicks this button the Masterpass wallet opens. To ensure the best consumer experience, the Masterpass button should be placed as early as possible, i.e. prior to the collection of shipping and billing data. In this respect it is also possible to place the button directly on an item’s details page so your consumer can buy the selected item by just one click on the Masterpass button, i.e. doing an express checkout. This is also a very convenient alternative to handle a "guest checkout" when your consumer does not register in your online shop.

This button can be inserted via a JavaScript method which inserts, when executed, a Masterpass button into a specified HTML element in your online shop. You can alternatively create your own button which invokes a specific JavaScript method. For further information on the Masterpass logo and Masterpass button visit branding recommendations.

Continuing in your online shop

After the transaction with Masterpass there are two ways to forward your consumer:

  • Redirect to a new page in your online shop. On this page you can continue with the checkout process or handle a cancel or failure situation wich occurred during the Masterpass interaction. This redirect page will also be called if no JavaScript can be executed or if your consumer uses a mobile device since the Masterpass wallet is opened in a redirect and not in an overlay when using mobile devices.

  • Define JavaScript methods. You can use JavaScript methods to add any interactivity and functionality you would like to have in your checkout process. Specified methods will be called if your consumer finishes or cancels the process or a failure occurs.

Reading a wallet resource

In the Masterpass wallet resource which was created for information transfer between your online shop and Masterpass, data are stored as a result of your consumer’s interaction with Masterpass. You may retrieve the following information from this Masterpass wallet resource and use it for further payment processing:

  • Shipping address details as selected by the consumer.

  • Billing address details as stated by the consumer when adding the card details to the wallet.

  • Anonymized card details such as maskedPan or hashedPan [1].

  • Consumer contact details such as e-mail and phone number.

  • transactionId which is created by Masterpass and used to post back the final transaction results to Masterpass.

  • Masterpass wallet resource ID you received when the wallet resource was created.

Please be aware that the name of the person specified in the shipping address may differ from the name your consumer entered as contact information.

As the shipping address is known after retrieving this information, you may use the above mentioned data and take for example the following actions prior to continuing with the usual payment process, i.e. requesting payment authorization:

  1. Calculating the shipping costs and informing the consumer accordingly.

  2. Including intermediate pages to give the consumer advertising information which is of interest for consumers from the relevant shipping country.

  3. Including cross-selling or up-selling options to offer consumers the possibility to buy related or complementary items.

  4. Redeeming coupons or offering discounts.

Initiating the payment process

After a successful interaction between your consumer and Masterpass the payment can be initiated with a POST request. This request triggers the payment process. The response for the payment state is "pending" because the payment is not yet completely processed.

Receiving the final transaction result

To receive the final result of the payment process there are two possibilities:

  • Checking the state repeatedly with a GET-request to the same resource.

  • Stating a notification URL. This URL will be requested one time only when the final payment process state is reached.

Once the final state is determined you can provide your consumer with information on the final result of the payment process, either SUCCESS or FAILURE, and for the latter case e.g. offer an alternative payment method.

1. hashedPan must be explicitly enabled by our support teams.