Last update 20/04/2016

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 Ingenico ePayments 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 Ingenico ePayments 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 Ingenico ePayments e-Commerce, you need to configure https://secure.ogone.com/ as the domain of your checkout project.
  • If you integrate with Ingenico ePayments DirectLink, you need to configure your own domain (usually that of your website) as the domain of your checkout project. 

4.2 Ingenico ePayments account

Once your MasterPass account is set up, you can configure MasterPass in your Ingenico ePayments 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 Ingenico ePayments 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 Ingenico ePayments e-Commerce:

  • No additional integration: If you redirect your customers to the Ingenico ePayments 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 Ingenico ePayments 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 Customer Care team 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 Ingenico ePayments 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 Ingenico ePayments 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 Ingenico ePayments 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 Ingenico ePayments 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 Ingenico ePayments 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 Ingenico ePayments 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 Ingenico ePayments 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 Ingenico ePayments Account ID FlowersInc
PSWD Your API-user's password ****....
USERID Your API-user FlowIncAPI

More information about these fields can be found in your Ingenico ePayments 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 Ingenico ePayments 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).

This website uses cookies to be able to give you the best user experience. If you don't want to accept these cookies, we allow you to change the cookie settings. Click 'Accept' to allow all cookies from this website.

Cookie settings

Introduction

Functional

Functional cookies are required for the website to operate correctly. These cookies cannot be disabled.

Optimized

Optimization cookies allow us to analyze site usage so we can measure and improve our website.
This is the default level.

Personalized

Personalization cookies are used for social media and advanced personalization. They allow us to show you information related to your company.


Example functionality allowed

  • Store country preference
  • Store language preference

Example functionality not allowed

  • Saving personal data
  • Anonymous tracking via Google Analytics
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics

Example functionality not allowed

  • Saving personal data
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics
  • Serve content relevant to your interests
  • Serve ads relevant to your interests
  • Tracking for remarketing purposes

Example functionality not allowed

  • Saving personal data