Last update 6/09/2018

1. Introduction

MasterPass is an e-wallet service by MasterCard. It allows your customers to securely store and share their e-payment data (card number, address, reward program, etc.) with the websites and mobile apps they work with.

In the MasterPass environment, the customer chooses the credit card he wants to pay with. The financial transaction is done with your usual credit card acquirer.

MasterPass can be used with ePDQ e-Commerce and DirectLink.

2. Payment process

2.1 e-Commerce

MasterPass e-Commerce flow

MasterPass DirectLink flow

3. Registration

If you haven't already done so, to register for your merchant account with MasterPass, please go to https://masterpass.com/SP/Merchant/Home and follow the required steps.

Once you've registered, you can continue to the Configuration chapter.

4. Configuration

For MasterPass to function properly, you first need to configure your MasterPass account. Once you've done so, you can configure the MasterPass payment method in your ePDQ account accordingly.

4.1 MasterPass account

In your MasterPass account, you can configure different checkout projects. Please consult the MasterPass documentation for further information on the creation and configuration of checkout projects.

A specific guide on MasterPass Merchant Checkout is available to you here:

https://developer.mastercard.com/documentation/masterpass-merchant-integration-v7

Note

  • If you integrate with ePDQ e-Commerce, you need to configure https://payments.epdq.co.uk/ as the domain of your checkout project.
  • If you integrate with ePDQ DirectLink, you need to configure your own domain (usually that of your website) as the domain of your checkout project. 

4.2 ePDQ account

Once your MasterPass account is set up, you can configure MasterPass in your ePDQ Account > Configuration > Payment methods.

The following data has to be configured:

Configuration data

Description

Example

Merchant ID Name of the checkout project Project 12
Checkout Identifier Checkout identifier provided by MasterPass a4a7w2omluuakh4k0t44k1h13u0z7m21hv

Note: Make sure that the Merchant ID you enter in your ePDQ account is the same as the one in your MasterPass account.

5. Integration

The integration of MasterPass is possible with both e-Commerce and DirectLink.

If you have an e-Commerce integration, only basic integration is required. However, if you want to offer MasterPass via DirectLink, various additional fields for e.g. delivery (shipping) and invoicing (billing) are required. Of course, in the last event, that also means you can retrieve much more details per transaction/customer.

Note: You can't offer MasterPass simultaneously via DirectLink and e-Commerce within the same PSPID

5.1 e-Commerce

Depending on your type of integration, either a basic or no integration is required with ePDQ e-Commerce:

  • No additional integration: If you redirect your customers to the ePDQ payment page without pre-selection of the payment method on your own site, you don't need to do anything. Once MasterPass is activated in your ePDQ account, it will be automatically included in the payment method list on the payment page.
  • Use of PM and BRAND: If the selection of the payment method is done on your own site, meaning that the customer is redirected from your site straight to the page of the requested payment method, you will be making use of the PM and BRAND parameters:

Parameter

Value

PM MasterPass
BRAND MasterPass
  • Shopping cart details: You can optionally send along details of the shopping cart items, which are sent on to MasterPass. The following fields are supported:
Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters

Parameter

Description

Format
ITEMCATEGORY*xx*
Item category (replace *xx* with a number to send multiple items: ITEMCATEGORY1, ITEMCATEGORY2, etc.)
AN, 50
ITEMID*xx*
Item identifier (replace *xx* with a number to send multiple items: ITEMID1, ITEMID2, etc.)
AN, 15
ITEMNAME*xx*
Item name (replace *xx* with a number to send multiple items: ITEMNAME1, ITEMNAME2, etc.) AN, 40
ITEMPRICE*xx*
Item price (replace *xx* with a number to send multiple items: ITEMPRICE1, ITEMPRICE2, etc.) N, 50
ITEMQUANT*xx*
Item quantity (replace *xx* with a number to send multiple items: ITEMQUANT1, ITEMQUANT2, etc.) N, 50
ITEMVATCODE*xx*
Item VAT code (replace *xx* with a number to send multiple items: ITEMVATCODE1, ITEMVATCODE2, etc.) N, 50
TAXINCLUDED*xx*
  • If this field is equal to 1, the ITEMPRICEX is considered to include VAT, and our system will not calculate the VAT for the item.
  • If this field is equal to 0 (or left blank, or not sent) our system will calculate the VAT for the item based on the ITEMVATCODEX This feature is intended to avoid any issues when rounding off the order line totals.
(replace *xx* with a number to send multiple items: TAXINCLUDED1, TAXINCLUDED2, etc.)
N, 1 (0/1)

For more information, go to e-Commerce.

  • Deactivate 3-D Secure: Send FLAG3D="N" if you want to deactivate 3-D Secure for a transaction. Note: If 3-D Secure is disabled in your MasterPass account, sending "Y" will not override this setting.

5.1.1 Feedback

Depending on your configuration, the PM, BRAND and other default and selected parameters are returned with the redirection URLs (ACCEPTURL etc.) and/or the post-sale (server-to-server) feedback.

Please note though, with the PM and BRAND parameters not "MasterPass" but the credit/debit card brand (MasterCard, Maestro, etc.) are returned. So, to identify your MasterPass transactions from normal credit and debit transactions, an extra column can be added in your transaction overviews. Please contact our our ePDQ Support to have this column added.

For more information on your downloaded reports, please refer to the Reporting chapter.

With MasterPass via DirectLink you'll send 3 API-calls:

  1. With the first call you retrieve the redirection URL to send the customer to MasterPass
  2. With the second call you retrieve the customer's delivery and invoicing address details
  3. With the third call you request the financial transaction (you can update the amount in this step).

Configuration of dynamic feedback parameters

To guarantee a flawless DirectLink process, it's of the utmost importance to have all relevant parameters returned to your system.

You must therefore configure the dynamic feedback parameters in your ePDQ account accordingly:

Go to: Configuration > Technical information > Transaction feedback > Directlink: Dynamic parameters, and move all the relevant fields (*) from the "Available" to the "Selected" box.

(* In each of the next "Calls" is mentioned which parameters will be returned to you and when).

 

With the first call you retrieve the redirection URL, which you'll receive on the ACCEPTURL.

You submit the default parameters that you use for most transaction requests in DirectLink: AMOUNT, CURRENCY, ORDERID, PSPID, PSWD, REFKIND and USERID (of API-user).

Additionally, the following fields must or can be sent:

Parameter

Description

Value/Format

Mandatory (Y/N)
PM Payment method MasterPass Y
BRAND Payment method (brand) MasterPass Y
ACCEPTURL The address which you'll receive the redirection URL on URL Y
FLAG3D Send "N" if you want to deactivate 3-D Secure for a transaction.

Note: If 3-D Secure is disabled in your MasterPass account, sending "Y" will not override this setting.

N N
TXSHIPPING Indicates if you'll use shipping data

0 (No)
1 (Yes)

N
TXSHIPPINGLOCATIONPROFILE Indicates a group of countries where you want to sell (a selection of) your products.
You create and configure this "profile" in your MasterPass account.
Name of the group, e.g. "Europe" or "benelux" N

More information about these fields can be found in your ePDQ account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.

The following parameters are automatically returned to you in the XML response:

Parameter

Description

Example

ORDERID The submitted order reference Order123
PAYID The unique ePDQ transaction reference 1251691421
REDIRECTIONURL The URL of the page the customer will be redirected to https://...

More information about these fields can be found in your ePDQ account. Just log in and go to : Support > Integration & user manuals > Technical guides > Parameter Cookbook.

Redirection step

In the redirection step, the customer gets redirected to the address that's returned with the "REDIRECTIONURL" in the first call.

On the page he's redirected to, the customer must log in to continue and choose his credit card, address etc.

If the customer successfully authenticates himself, you will receive the following parameters:

Parameter

Description

Example

ORDERID Order reference from Call 1 Order123
OAUTH_TOKEN Token to be submitted with the "TXTOKEN" parameter in Call 2 c295cf7d5b644cc8eff33f111f9f78a9
OAUTH_VERIFIER Verfier code to be submitted with the "TXVERIFIER" parameter in Call 2 4f4d992342145856e1edbdc67e899b08
CHECKOUT_RESOURCE_URL URL to be submitted with the "TXURL" parameter in Call 2 https://...

More information about these fields can be found in your ePDQ account. Just log in and go to : Support > Integration & user manuals > Technical guides > Parameter Cookbook.

If the customer was unable to authenticate himself or if he cancels, you will receive only the ORDERID and OAUTH_TOKEN. 

With a successful authentication after the redirection, you must send the data below to retrieve delivery (shipping) and invoicing (billing) information from the customer:

Parameter

Description

Example

Default parameters: AMOUNT, BRAND (MasterPass), CURRENCY, PM (MasterPass), PSPID, PSWD, REFKIND, USERID.
ORDERID Order reference from Step 1 Order123
TXTOKEN Value returned with the "OAUTH_TOKEN" parameter after redirection c295cf7d5b644cc8eff33f111f9f78a9
TXVERIFIER Value returned with the "OAUTH_VERIFIER" parameter after redirection 4f4d992342145856e1edbdc67e899b08
TXURL Value returned with the "CHECKOUT_RESOURCE_URL" parameter after redirection https://...

More information about these fields can be found in your ePDQ account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.

Note: If you don't send "TXVERIFIER" and/or "TXURL" at this step, meaning that the customer didn't authenticate or cancelled, the transaction will get the "Cancelled" status 1.

The following delivery and invoicing parameters are returned to you:

Parameter

Description

Example

ECOM_BILLTO_POSTAL_CITY Customer invoice town/city San Francisco
ECOM_BILLTO_POSTAL_COUNTRYCODE Customer Invoice country code (ISO) US
ECOM_BILLTO_POSTAL_STATEDESC Customer invoice country state California
ECOM_BILLTO_POSTAL_STREET_LINE1 Customer invoice street (line 1) Lombart Street 1207
ECOM_BILLTO_POSTAL_STREET_LINE2 Customer invoice street (line 2) 2nd Floor
ECOM_BILLTO_POSTAL_POSTALCODE Customer delivery postcode 94111
EMAIL Customer email address jack.brodrick@powell-hyde.com
CN Customer name Jack Brodrick
ECOM_BILLTO_POSTAL_NAME_LAST
Customer invoice last name (surname)
Brodrick
ECOM_BILLTO_POSTAL_NAME_FIRST Customer invoice first name
Jack
ECOM_BILLTO_TELECOM_PHONE_NUMBER
Customer invoice telephone number
+1 (415) 123-4567
ECOM_SHIPTO_POSTAL_CITY
Customer delivery town/city
San Francisco
ECOM_SHIPTO_POSTAL_COUNTRYCODE
Customer delivery country code (ISO)
US
ECOM_SHIPTO_POSTAL_STATEDESC
Customer delivery country state
California
ECOM_SHIPTO_POSTAL_STREET_LINE1
Customer delivery street (line 1)
Lombard Street 1207
ECOM_SHIPTO_POSTAL_STREET_LINE2
Customer delivery street (line 2)
Building 2, 3rd floor
ECOM_SHIPTO_POSTAL_POSTALCODE
Customer delivery postcode
94111
ECOM_SHIPTO_POSTAL_NAME_LAST
Customer delivery last name
Brodrick
ECOM_SHIPTO_TELECOM_PHONE_NUMBER Customer delivery phone number +1 (415) 123-4567

More information about these fields can be found in your ePDQ account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.

With the third call the financial transaction is requested. You must send the following parameters:

Parameter 

Description

Example

AMOUNT The final amount (x100), including delivery costs etc. 5620
BRAND MasterPass MasterPass
CURRENCY Currency which the final amount is processed with USD
ORDERID Order reference, same as in Step 1 and 2 Order123
PM MasterPass MasterPass
PSPID Your unique ePDQ Account ID FlowersInc
PSWD Your API-user's password ****....
USERID Your API-user FlowIncAPI

More information about these fields can be found in your ePDQ account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.

Important: DirectLink and Fraud detection

In order for our system to be able to check the customer’s IP address, merchants using DirectLink and Fraud detection need to send the customer's IP address in the “REMOTE_ADDR” field.

This way, customer's IP addresses can be properly matched against blacklists and whitelists, and IP velocity checks will not take the merchant's server IP address(es) into account.

Read more in Fraud detection and DirectLink.


You can optionally send along details of the shopping cart items, which are sent on to MasterPass. The following fields are supported:

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters

Parameter

Description

Format
ITEMCATEGORY*xx*
Item category (replace *xx* with a number to send multiple items: ITEMCATEGORY1, ITEMCATEGORY2, etc.)
AN, 50
ITEMID*xx*
Item identifier (replace *xx* with a number to send multiple items: ITEMID1, ITEMID2, etc.)
AN, 15
ITEMNAME*xx*
Item name (replace *xx* with a number to send multiple items: ITEMNAME1, ITEMNAME2, etc.) AN, 40
ITEMPRICE*xx*
Item price (replace *xx* with a number to send multiple items: ITEMPRICE1, ITEMPRICE2, etc.) N, 50
ITEMQUANT*xx*
Item quantity (replace *xx* with a number to send multiple items: ITEMQUANT1, ITEMQUANT2, etc.) N, 50
ITEMVATCODE*xx*
Item VAT code (replace *xx* with a number to send multiple items: ITEMVATCODE1, ITEMVATCODE2, etc.) N, 50
TAXINCLUDED*xx*
  • If this field is equal to 1, the ITEMPRICEX is considered to include VAT, and our system will not calculate the VAT for the item.
  • If this field is equal to 0 (or left blank, or not sent) our system will calculate the VAT for the item based on the ITEMVATCODEX This feature is intended to avoid any issues when rounding off the order line totals.
(replace *xx* with a number to send multiple items: TAXINCLUDED1, TAXINCLUDED2, etc.)
N, 1 (0/1)


6. Reporting

In the files that you download via "View transactions" and "Financial history", the METHOD and BRAND columns show the values of the payment method that the customer used. In case of MasterPass, these values will be no different than those of normal credit card transactions.

Therefore, in order to distinguish which credit card transactions were actually initiated with MasterPass, you can add an extra field/column to your reports: "TO_WALLET"

To have this field added, you need to go to "Operations" > "Electronic reporting" and under the "Dynamic" structure" add the "[TO_WALLET]" field to the "Optional fields".

MasterPass Reporting

Once added, in the next file you download, the "TO_WALLET" column will be included and (when applicable) show the "MasterPass" value.

7. Extra features

Alias Manager (optional)

If you have the Alias Manager option enabled, you can create aliases with MasterPass transactions just as you'd do for normal credit card transactions. Manual alias creation, however, is not supported with MasterPass.

For more information, go to Alias Manager.

3-D Secure

The use of 3-D Secure is managed from your MasterPass account. Whether or not 3-D Secure is activated for the credit cards in your ePDQ account has no influence on your MasterPass transactions.

However, when configured accordingly, with every transaction the ECI value can be returned, indicating if 3-D Secure was used (ECI 5) or not (ECI 7).

*Call Charges: The following is a guide to call charge information from Business landlines within the UK.

Barclaycard is a trading name of Barclays Bank PLC. Barclays Bank PLC is authorised by the Prudential Regulation Authority and regulated by the Financial Conduct Authority and the Prudential Regulation Authority (Financial Services Register number: 122702). Registered in England. Registered No. 1026167. Registered office: 1 Churchill Place, London E14 5HP

Barclays Bank PLC subscribes to the Lending Code which is monitored and enforced by the Lending Standards Board. Further details can be found at www.lendingstandardsboard.org.uk escape arrow


© Barclaycard 2016