Masterpass Integration for Wirecard Checkout Page
Masterpass Integration for Wirecard Checkout Page
To offer Masterpass to your consumers in your online shop, using Wirecard Checkout Page, we provide the following information.
Integration information
In order to make Masterpass available to your consumers, please contact our sales teams. After activation and corresponding setup by our support teams, Masterpass will appear among the card brands (see screen below) as well as on the payment method selection page.
Additionally you can either state MASTERPASS as sole parameter value paymentType to forward the consumer directly to Masterpass, or as additional value to offer a selected number of payment methods.
Your consumer selects Masterpass within Wirecard Checkout Page and initiates the payment process just by logging into the Masterpass wallet and selecting a credit card and optionally a shipping address.
Express checkout
You can add a Masterpass button e.g. on the details page of an item to provide an express checkout. This button invokes Wirecard Checkout Page by using the usual POST request and initiates a payment for the total amount including shipping costs. After your consumer has paid, the resulting information is sent to the confirmation URL including the selected shipping address.
Shipping costs and shipping address
For your consumers' convenience you can request the shipping address from your consumer directly during the Masterpass wallet interaction.
When your consumer selected an address within Masterpass, you will receive the shipping address information in the response parameters after the payment process. Therefore you need to calculate the possible shipping costs for the address your consumer will choose when invoking Wirecard Checkout Page. In contrast, with Wirecard Checkout Seamless you receive the shipping address before payment initiation. There are two possibilities for the shipping costs calculation. You can either restrict the shipping address selection area and calculate the precise costs for a certain area, or request the shipping costs for world wide shipping and then only deposit the actual costs. As a third possibility, the selection of a shipping address may be disabled for particular cases.
Restricting the addresses
You can restrict the selection of a shipping address by setting the parameter shippingProfile to a predefined shipping profile, e.g. if you make restrictions for only one country or for a certain region such as D-A-CH. Your consumer can select an address in Masterpass within the shipping profile area. Thus you can calculate the shipping costs for this area.
For using these shipping profiles or setting up new shipping profiles to restrict your shipping address area, contact our support teams.
Unrestricted addresses
If you do not set the shippingProfile parameter, the address selection is areawise unrestricted, i.e. any address from all over the world can be selected which makes shipping cost calculation impossible. However, you can request authorization from your consumer for your highest worldwide shipping costs and inform your consumer that the final costs might be lower depending on the shipping address selected. The actual amount you deposit may thus be lower than the authorized amount and includes the actual shipping costs to the address your consumer has finally selected.
No addresses
If your consumer already has submitted a shipping address in a previous step and you submit your consumer’s shipping address to Wirecard Checkout Page via the request parameters consumerShipping*, the possibility of a selection within Masterpass wallet will be automatically disabled. Therefore it is advisable to always include the shipping address, if known, in the request parameters for Wirecard Checkout Page in order to disable the address selection. Otherwise you might end up with two addresses, i.e. one from a previous step and one from Masterpass.
For digital goods or if a shipping address is always entered in a previous step disabling the address selection may be useful. You can disable the shipping address selection in the Masterpass wallet of your consumer by setting the parameter shippingProfile to NO_SHIPPING.
Tabular overview
The following table explains in which cases your consumer is shown an address selection within Masterpass. Whether the address selection is displayed or not depends on the request parameters shippingProfile and consumerShipping*. The parameters consumerBilling* are not taken into account.
Consumer can |
|
|||
::: |
Not set |
|
Restricted |
|
|
Not set |
Yes (1) |
No (2) |
Yes (3) |
::: |
Set |
No (4) |
No (5) |
No (6) |
-
consumerShippingLastName=&shippingProfile= -
consumerShippingLastName=&shippingProfile=NO_SHIPPING -
consumerShippingLastName=&shippingProfile=SP-0001 -
consumerShippingLastName=Doe&shippingProfile= -
consumerShippingLastName=Doe&shippingProfile=NO_SHIPPING -
consumerShippingLastName=Doe&shippingProfile=SP-0001
Optional request parameters
To display the shopping basket information to your consumer the Shopping basket parameters can be used.
Please note the length restrictions that apply for this payment method and the following shopping basket parameters.
| Parameter | Within fingerprint | Data type | Short description |
|---|---|---|---|
basketItem(n)ArticleNumber |
Required if used. |
Alphanumeric with special characters and with a variable length of up to 127 characters. |
Unique ID of article n in shopping basket. |
basketItem(n)Description |
Required if used. |
Alphanumeric with special characters and with a variable length of up to 500 characters. |
Product description of article n in shopping basket. |
basketItem(n)ImageUrl |
Required if used. |
Alphanumeric with special characters and with a variable length of up to 500 characters. |
URL to an image of each item. |
basketItem(n)Name |
Required if used. |
Alphanumeric with special characters and with a variable length of up to 127 characters. |
Product name of article n in shopping basket. |
The request parameter financialInstitution can be used to define the credit card brands allowed for the current payment. Thus only the listed brands can be selected by your consumer during the interaction with the Masterpass wallet.
As regards the optional request parameters customerStatement and orderReference we refer to the restrictions that are applicable for credit cards since these parameters depend on the relevant acquirers and are therefore more restricted in length and allowed characters. For more information and details visit Optional request parameters.
Additional optional request parameter
The following request parameter is available when selecting the payment method Masterpass.
| Parameter | Data type | Description |
|---|---|---|
Alphabetic |
String of shipping profile ID, e.g. "SP-0001" including the countries Germany, Austria and Switzerland. |
Details parameter shippingProfile
These shipping profiles apply both for Wirecard Checkout Page and Wirecard Checkout Seamless.
| Shipping profile name | Countries | Shipping profile ID |
|---|---|---|
DACH |
Germany, Austria, Switzerland |
SP-0001 |
SLO |
Slovenia |
SP-0002 |
WORLD (default) |
All countries |
SP-0003 |
AUSTRIA |
Austria |
SP-0004 |
For using these shipping profiles or setting up new shipping profiles to restrict your shipping address area, contact our support teams.
If the parameter shippingProfile and the parameters relating to the consumer shipping information are not set, all addresses can be selected by your consumer. If the value for shippingProfile is set to NO_SHIPPING (for Wirecard Checkout Page), no shipping address can be selected (Wirecard Checkout Page).
Additional response parameters
When using Masterpass, Wirecard Checkout Page will return additional parameters to your online shop.
Your consumer is asked for a billing address when adding a credit card to the Masterpass wallet. This billing address information is provided when the respective card is selected by your consumer.
If your consumer has selected a shipping address, the following shipping address related parameters are returned.
| Parameter | Data type | Short description |
|---|---|---|
masterpassBillingAddressCity |
Alphanumeric with special characters. |
Billing address city. |
masterpassBillingAddressCountry |
Alphabetic with a fixed length of 2. |
Billing address country code (ISO 3166-1). |
masterpassBillingAddressCountrySubdivision |
Alphanumeric with special characters. |
Billing address country subdivision. |
masterpassBillingAddressPostalCode |
Alphanumeric with special characters. |
Billing address postal code. |
masterpassBillingAddressAddressLine1 |
Alphanumeric with special characters and a variable length of up to 40. |
Billing address with name of street and number. |
masterpassBillingAddressAddressLine2 |
Alphanumeric with special characters and a variable length of up to 40. |
Additional billing address information. |
masterpassBillingAddressAddressLine3 |
Alphanumeric with special characters and a variable length of up to 255. |
Additional billing address information. |
masterpassCardFirstname |
Alphanumeric with special characters and a variable length of up to 20. |
Card holder first name. |
masterpassCardLastname |
Alphanumeric with special characters and a variable length of up to 20. |
Card holder last name. |
masterpassCardEmail |
Alphanumeric with special characters and a variable length from 5 to 512. |
Card holder e-mail address. |
masterpassShippingAddressRecipientName |
Alphanumeric with special characters. |
Shipping address recipient name. |
masterpassShippingAddressRecipientPhoneNumber |
Alphanumeric with special characters |
Shipping address recipient phone number using country code (ISO 3166-1). |
masterpassShippingAddressCity |
Alphanumeric with special characters. |
Shipping address city. |
masterpassShippingAddressCountry |
Alphabetic with a fixed length of 2. |
Shipping address country code (ISO 3166-1). |
masterpassShippingAddressCountrySubdivision |
Alphanumeric with special characters. |
Shipping address country subdivision. |
masterpassShippingAddressPostalCode |
Alphanumeric with special characters. |
Shipping address postal code. |
masterpassShippingAddressAddressLine1 |
Alphanumeric with special characters and a variable length of up to 40. |
Shipping address with name of street and number. |
masterpassShippingAddressAddressLine2 |
Alphanumeric with special characters and a variable length of up to 40. |
Additional shipping address information. |
masterpassShippingAddressAddressLine3 |
Alphanumeric with special characters and a variable length of up to 255. |
Additional shipping address information. |
Data are only returned if they are provided by your consumer, e.g. masterpassShippingAddressAddressLine2 may not be defined.
|