Masterpass
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 Hosted Payment Page and DirectLink
2. Payment process
2.1 Hosted Payment Page
2.2 DirectLink
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 Worldline 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
|
4.2 Worldline account
Once your MasterPass account is set up, you can configure MasterPass in your Worldline 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 Worldline account is the same as the one in your MasterPass account.
5. Integration
The integration of MasterPass is possible with both Hosted Payment Page and DirectLink.
If you have an Hosted Payment Page 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 Hosted Payment Page within the same PSPID
5.1 Hosted Payment Page
Depending on your type of integration, either a basic or no integration is required with Worldline Hosted Payment Page:
- No additional integration: If you redirect your customers to the Worldline 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 Worldline 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:
|
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* |
|
N, 1 (0/1) |
For more information, go to Hosted Payment Page.
- 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 department to have this column added.
For more information on your downloaded reports, please refer to the Reporting chapter.
5.2 DirectLink
With MasterPass via DirectLink you'll send 3 API-calls:
-
With the first call you retrieve the redirection URL to send the customer to MasterPass
-
With the second call you retrieve the customer's delivery and invoicing address details
-
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 Worldline 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). |
5.2.1 Call 1: Get redirection URL + Redirection step
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) |
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 Worldline 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 Worldline 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 Worldline 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 Worldline 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.
5.2.2 Call 2: Get Delivery and Invoicing data
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 Worldline 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 |
| 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 Worldline account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.
5.2.3 Call 3: Transaction
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 Worldline Account ID | FlowersInc |
| PSWD | Your API-user's password | ****.... |
| USERID | Your API-user | FlowIncAPI |
More information about these fields can be found in your Worldline 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:
|
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* |
|
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".
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 Worldline 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).