This topic provides information on the MasterPass™ integration process.
Lightbox Integration...82 Standard checkout...84 Standard Checkout Callback... 84 Redirect to Merchant Callback URL Parameters for Standard Checkout... 85 Checkout Callback Method Example...86 Implementing DSRP and Tokenization...86 DSRP Extension Points in the MasterPass Merchant API... 87 DSRP Extension Points in the MasterPass Checkout XML... 90 Tokenization Extension Points in the MasterPass Checkout XML...94 Split/Partial Shipments and Recurring Payment Transactions...97 3-D Secure Considerations... 97 Testing DSRP... 97 Pairing with MasterPass Merchant outside of Checkout...97 Invoke MasterPass UI ... 98 Return Checkout Callback... 99 Pairing with MasterPass Merchant During Checkout...99 Invoke MasterPass UI for Pairing During Checkout... 100 Return Checkout Callback... 101 Pairing during Checkout Callback Method Example... 101 Return Checkout (Checkout after Pairing)...102 Invoke MasterPass UI for Connected Checkout... 102 Connected Checkout Callback...103 MasterPass Service Descriptions...104 Request Token Service...104 Shopping Cart Service...104 Merchant Initialization Service ...106 Access Token Service...106 Retrieve Payment, Shipping Data, Rewards, and 3-D Secure Details...106 Postback Service... 108 Android and iOS App Integration ... 109 Completing the Integration...112
For a step-by-step guide through integration and illustration of the various calls to MasterPass, download code samples available in various languages such as Java, C#, PHP, and Ruby. You can also access the sample code for correct implementation of signature base string and exchanges with MasterPass on the Merchant Checkout Services—Sample Code page.
Lightbox Integration
Lightbox integration is required to launch the MasterPass user interface.
Procedure
1. To invoke the Lightbox, merchants must include the following scripts to the page on which they are adding the Buy with MasterPass or Connect with MasterPass buttons.
NOTE: Merchants invoking the Lightbox from an iFrame must include both the sandbox and production scripts on the parent (outer) web page and the iFrame source that is invoking MasterPass Lightbox.
a. Add jQuery. Include this jQuery file from the public jQuery repository: https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js b. Add the MasterPass Integration Script to your checkout page.
– Sandbox https://sandbox.static.masterpass.com/dyn/js/switch/integration/ MasterPass.client.js – Production https://static.masterpass.com/dyn/js/switch/integration/ MasterPass.client.js
2. Add the MasterPass Checkout Button to your checkout page.
NOTE: Be sure to change the image name to the image size and locale that you would like to use. For further details, refer to MasterPass Branding.
3. Launch MasterPass checkout on the click of the button.
Parameters for Invoking MasterPass Checkout
Parameter Data Type Required Description
requestToken String Yes Your request token from
the Standard Checkout flow
callbackUrl String Yes The URL to which the
browser must redirect when checkout is complete
NOTE:
This is required even if you use callback functions. merchantCheckoutId String Yes Your unique checkout
identifier from the MasterPass Merchant Portal
allowedCardTypes String array No Card types accepted by merchant
Version String No (default: v6) Masterpass API Version successCalback Function No The function that will be
called if the MasterPass flow ends successfully failureCallback Function No The function that will be
called if the MasterPass flow ends in a failure
Parameter Data Type Required Description
cancelCallback Function No The function that will be called if the user cancels the MasterPass flow 4. Handle the callback on completion of checkout.
On completion of checkout (success, failure or cancellation), the control will be transferred to your system either via the callback url or the callback functions.
NOTE: If MasterPass is forced to go full screen, then you will not be able to call the JavaScript callback method and must use a merchant callback redirect. As a result, you must support always support the callback url redirect.
Standard checkout
The following steps are necessary to integrate a standard MasterPass checkout. For more details, click on each of the following steps:
1. Request Token Service 2. Shopping Cart Service
3. Merchant Initialization Service
4. Invoke MasterPass UI (Lightbox) for checkout
5. Standard Callback method and Redirect to callback URL 6. Access Token Service
7. Retrieve Payment, Shipping Data, Rewards, and 3DS Details 8. Authorize Payment through payment processor
9. Postback Service
NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must use the Merchant Initialization service to send the Origin URL.
Standard Checkout Callback
Once a checkout is completed, MasterPass™ will return context to the merchant.
This can be done via the following:
NOTE: If MasterPass is forced to go full screen, then you will not be able to call the JavaScript callback method and must use a merchant callback redirect. As a result, you must support both the callback method and the redirect.
• A callback URL: MasterPass uses the callback URL ( callbackUrl ) parameter passed when invoking lightbox or oauth_callback from the request token call to direct back to the merchant site when lightbox is rendered in full-screen mode.
• A JavaScript callback method: Use the failureCallback and successCallback parameters to give control back to the page that initiated the Lightbox without any redirects. These parameters must be set when invoking the MasterPass lightbox user interface. Use the cancelCallback parameter to notify a MasterPass merchant that a consumer has canceled their transaction.
Callback Parameters for Standard Checkout
Parameter Data Type Required Description
mpstatus String Success, Failure,
Cancel
Indicates whether the MasterPass flow was completed and results in success, failure or cancel
oauth_token String Used in conjunction with
oauth_verifier to retrieve the access token
oauth_verifier String Used in conjunction with
oauth_token to retrieve the access token
checkout_resource_url String API URL to retrieve checkout information
Example of Callback URL (Successful Transaction) http://www.somemerchant.com/checkoutcomplete.htm? mpstatus=success checkout_resource_url=https%3A%2F%2Fapi.mastercard.com%2Fmasterpass %2Fv6%2Fcheckout%2F17%3Fwallet %3Dphw& oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13& oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc Example of Callback URL (Cancelled Transaction)
http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=cancel Example of Callback Function
function handleCallbackSuccess (data) {
callYourServerWith(data.oauth_token, data.oauth_verifier, data.checkout_resource_ur);}
Redirect to Merchant Callback URL Parameters for Standard Checkout
Merchants must use the following data parameters to complete the MasterPass™ Standard
Checkout flow.
mpstatus
Success, failure, or cancel. Indicates whether MasterPass flow was completed.
oauth_token
Used in concert with oauth_verifier to retrieve access token. oauth_verifier
Used in concert with oauth_token to retrieve access token. checkout_resource_url
API URL to retrieve checkout information.
Following are examples of the redirect to merchant callback URLs when a transaction is successful or cancelled:
Redirect to Merchant Callback URL Example for a Successful Transaction http://www.somemerchant.com/checkoutcomplete.htm? mpstatus=success&checkout_resource_url=https%3A%2F%2Fsandbox.api.mastercard.com %2Fmasterpass %2Fv6%2Fcheckou t%2F10189977%3Fwallet %3Dphw&oauth_verifier=6c50838e31b7441e6eafa222938545288 9255b13&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc
Redirect to Merchant Callback URL Example for a Cancelled Transaction http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=cancel Checkout Callback Method Example
The following is a sample of the checkout callback method.
function onSuccessfulCheckout(data) {
document.getElementById('oauthToken').value=data.oauth_token; document.getElementById('oauthVerifer').value=data.oauth_verifier; document.getElementById('checkoutUrl').value=data.checkout_resource_url; }
Implementing DSRP and Tokenization
A MasterPass™ transaction must meet the following conditions to be processed as a Digital
Secure Remote Payment (DSRP) transaction.
• The merchant or service provider must have successfully implemented MasterPass Merchant API version 6, including the merchant initialization call and the new DSRP and tokenization extension points.
• The merchant or service provider must have successfully implemented MasterPass
Merchant Mobile Checkout SDK that facilitates consumer transactions from the merchant Android™ application to an Android MasterPass wallet application (app-to-app). DSRP
cryptograms can currently only be generated for transactions that occur for these Android app-to-app use cases. If Mobile Checkout is available in your country, refer to the
MasterPass - Merchant Android SDK page on the MasterCard Developer Zone for more information.
• Systems must be in place to correctly identify authorizations for split/partial shipments and recurring payments so that the DSRP data is accurately processed for subsequent
authorizations (for more information, refer to the section below).
• The payment gateway and acquirer must have updated their Dual Message and Single Message System interfaces to pass and receive DSRP data elements (refer to the Digital Secure Remote Payment—Acquirer Implementation Guide for more information). MasterPass recommends that merchants or service providers contact their payment gateway(s) and acquirer(s) to:
– Understand the changes the gateway and acquirer are making to support DSRP.
– Identify any corresponding work that the merchants or service providers must complete. • The consumer’s card issuer/wallet provider must have successfully updated their interfaces
to pass and receive DSRP data elements.
• The consumer has elected to pay with a card that has been digitized (for MasterPass Mobile Checkout transactions, this will be a MasterCard Digital Enablement Services [MDES]-enabled MasterCard brand card).
If any of these conditions has not been met, the transaction will be considered a standard MasterPass transaction.
For MasterPass transactions that start on a merchant's Android application and complete on a consumer’s Android MasterPass wallet application, a DSRP cryptogram will be generated. A DSRP cryptogram will be accompanied by a 16-digit token rather than the actual MasterCard card brand primary account number (PAN). Whenever a token is passed instead of the actual account number, the last four digits of the consumer’s actual PAN will be passed in an extension point so that they can be displayed to the consumer if so desired.
DSRP Extension Points in the MasterPass Merchant API
Merchants and service providers must use the merchant initialization call and the Digital Secure Remote Payment (DSRP) extension points in the MasterPass™ Merchant API version 6 to
pass and receive DSRP data elements and values.
MerchantInitializationRequest with DSRP Extension Points V6—XML Details
Element Description Type Min–Max
MerchantInitializationRe quest Root Element XML – MerchantInitializationRe quest.OAuthToken Request Token (oauth_token) returned by call to the request_token API – MerchantInitializationRe quest.OriginUrl
Identifies the URL of the page that initializes the lightbox
string NA
Element Description Type Min–Max MerchantInitializationRe quest.ExtensionPoint.DS RP.DSRPOptions.Option. BrandId Required for DSRP transactions. Identifies the card brands for which DSRP is desired. The valid card IDs are
master and maestro . string MerchantInitializationRe quest.ExtensionPoint.DS RP.DSRPOptions.Option. AcceptanceType Required for DSRP transactions. Indicates the type(s) of cryptograms the merchant or service provider can accept. Valid types are: UCAF
and/or ICC (see descriptions that follow).
MasterPass passes the most secure selection (ICC) if both acceptance types are indicated.
alpha MerchantInitializationRe quest.ExtensionPoint.DS RP.UnpredictableNumbe r Optional for DSRP transactions. EMV- quality random number generated by the merchant, service provider, or—if null—by MasterPass and Base64 encoded
4-byte binary string 8
A cryptogram is the output of the process of transforming clear text into ciphertext for security or privacy.
There are two forms in which the DSRP cryptograms may be generated and sent depending on the capabilities of the merchant, payment gateway, and acquirer systems:
• UCAF™ data: In this case, the EMV cryptogram—and a subset of the EMV data—are carried in the Universal Cardholder Authentication Field (UCAF) in data element (DE) 48, subelement 43.
The UCAF cryptogram is Base64 encoded and is up to 32 characters in length and contains a subset of the EMV data including the application cryptogram, application transaction
Most merchant and acquirer systems are configured today to support UCAF data transmission.
• Full EMV data: In this case the full set of EMV data is carried in data element (DE) 55 Integrated Circuit Card (ICC) System-Related Data in transaction messages.
The ICC cryptogram is Hex encoded and is up to 512 characters in length as it contains the full set of EMV data including all the data listed previously for UCAF plus other information such as issuer application data, terminal verification results, cryptogram information data (CID), cardholder verification method (CVM) results, authorized amount, other amount, transaction currency code, transaction date, transaction type, application primary account number (PAN), application expiration date, and terminal country code.
While ICC is considered the more secure, recommended option, many merchant and acquirer systems today are not yet configured to support this data element.
If the merchant and acquirer systems are enabled to send and receive the DSRP cryptogram data in both the UCAF and/or ICC (DE 55) forms, the merchant or service provider can specify both UCAF and ICC. In this instance, MasterPass passes the cryptogram with the highest level of security (ICC) if the consumer’s wallet provider also supports ICC. If the consumer’s wallet cannot support ICC, MasterPass passes the UCAF form of the cryptogram.
The Unpredictable Number is four-byte binary data that is randomly generated (per the EMVCo Specification Bulletin No. 144) by either the merchant, service provider, or MasterPass (which is then passed back to the merchant or service provider at the end of the transaction). The presence of the Unpredictable Number provides an additional layer of security by
providing an element that is unknowable and unique to a specific transaction. This prevents a cryptogram from being used for anything other than the transaction for which it was
generated. MasterPass recommends that you do not populate the Unpredictable Number element; in such cases, MasterPass will generate the value on your behalf. However, if you want to generate your own random/unpredictable numbers—in order to able to validate the transaction easily by comparing the number that you generated with what was returned to you—refer to EMVCo’s requirements for this value in the “Random Number Generation” section of the EMV Acquirer and Terminal Security Guidelines document. After generation, the value must then be Base64 encoded and passed in the Unpredictable Number extension point in the Merchant Initialization Request OpenAPI call.
MerchantInitializationRequest with DSRP Extension Points—Sample
URL: https://api.mastercard.com/masterpass/v6/merchant-initialization
NOTE: The following example illustrates a case in which a merchant has chosen to generate the unpredictable number; if the UnpredictableNumber field is left null, MasterPass will
generate the value on behalf of the merchant. <MerchantInitializationRequest> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> <OriginUrl>https://somemerchant.com</OriginUrl> <ExtensionPoint> <DSRP> <DSRPOptions> Standard checkout
<Option> <BrandId>master</BrandId> <AcceptanceType>UCAF</AcceptanceType> </Option> </DSRPOptions> <UnpredictableNumber>413142==</UnpredictableNumber> </DSRP> </ExtensionPoint> </MerchantInitializationRequest> MerchantInitializationResponse—Sample <MerchantInitializationResponse> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> <ExtensionPoint> <UnpredictableNumber>413142==</UnpredictableNumber> </ExtensionPoint> <MerchantInitializationResponse>
DSRP Extension Points in the MasterPass Checkout XML
After a remote transaction has been facilitated and secured via Digital Secure Remote Payment (DSRP), the MasterPass™ wallet will generate a cryptogram that the merchant or
service provider will receive in the Checkout XML.
The "Checkout XML—Sample with UCAF Cryptogram" illustrates a case in which a merchant or service provider has indicated that it can only receive a UCAF cryptogram. The "Checkout XML—Sample with ICC Cryptogram" illustrates a case in which a merchant or service provider has indicated that it can receive (a) a UCAF or ICC or (b) an ICC crytogram. The elements shown in bold are elements that are impacted by the presence of a cryptogram.
• The AccountNumber element is a 16-digit, device-based token rather than the cardholder's actual card number.
• The ExpiryMonth and ExpiryYear elements indicate the expiration data of the provided token.
• The AuthenticateMethod element indicates that DSRP was the method utilized for this transaction.
• The DSRP ExtensionPoint elements are populated with the cryptogram, type, unpredictable number, and ECI flag. These extension points will usually be followed by token extension points described in more detail below.
Checkout XML—Sample with UCAF Cryptogram
Received from URL: https://api.mastercard.com/itf/masterpass/v6/checkout/{checkoutId} <Checkout> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <AccountNumber>5178058604388374</AccountNumber> <BillingAddress> <City>O fallon</City> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</Line1>
<Line2/>
<PostalCode>63368</PostalCode> </BillingAddress> <CardHolderName>Jane Doe</CardHolderName> <ExpiryMonth>6</ExpiryMonth> <ExpiryYear>2017</ExpiryYear> </Card> <TransactionId>286532912</TransactionId> <Contact> <FirstName>Jane</FirstName> <LastName>Doe</LastName> <NationalID>***********</NationalID> <Country>US</Country> <EmailAddress>[email protected]</EmailAddress> <PhoneNumber>1-3692581470</PhoneNumber> </Contact> <ShippingAddress> <City>O fallon</City> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</Line1>
<Line2/> <Line3/> <PostalCode>63368</PostalCode> <RecipientName>Jane Doe</RecipientName> <RecipientPhoneNumber>US+1-8734048394</RecipientPhoneNumber> </ShippingAddress> <AuthenticationOptions> <AuthenticateMethod>DSRP</AuthenticateMethod> </AuthenticationOptions> <WalletID>208</WalletID> <PreCheckoutTransactionId>a4c411b-18h26t-icni2rol-1-ics6caee-123y</ PreCheckoutTransactionId> <ExtensionPoint> <DSRP> <DSRPData>Qwertyuio0987654321asdfghjklpois</DSRPData> <DSRPDataType>UCAF</DSRPDataType> <UnpredictableNumber>413142==</UnpredictableNumber> <Eci>02</Eci> </DSRP> </ExtensionPoint>
Checkout XML—Sample with ICC Cryptogram
Received from URL: https://api.mastercard.com/masterpass/v6/checkout/{checkoutId}
NOTE: US merchants will not receive the PreCheckoutTransactionId element in the following example. <Checkout> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <AccountNumber>5178058604388374</AccountNumber> <BillingAddress> <City>O fallon</City> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</Line1>
<Line2/> <Line3/>
<PostalCode>63368</PostalCode> </BillingAddress>
<CardHolderName>Jane Doe</CardHolderName> <ExpiryMonth>6</ExpiryMonth> <ExpiryYear>2017</ExpiryYear> </Card> <TransactionId>286532912</TransactionId> <Contact> <FirstName>Jane</FirstName> <LastName>Doe</LastName> <NationalID>***********</NationalID> <Country>US</Country> <EmailAddress>[email protected]</EmailAddress>