The information contained in this document is proprietary and confidential to MasterCard International Incorporated, one or more of its affiliated entities (collectively "MasterCard"), or both. This material may not be duplicated, published, or disclosed, in whole or in part, without the prior written permission of MasterCard.
Trademark notices and symbols used in this document reflect the registration status of MasterCard trademarks in the United States. Please consult with the Customer Operations Services team or the MasterCard Law Department for the registration status of particular product, program, or service names outside the United States. All third-party product and service names are trademarks or registered trademarks of their respective owners.
A translation of any MasterCard manual, bulletin, release, or other MasterCard document into a language other than English is intended solely as a convenience to MasterCard members and other customers. MasterCard provides any translated document to its members and other customers "AS IS" and makes no representations or warranties of any kind with respect to the translated document, including, but not limited to, its accuracy or reliability. In no event shall MasterCard be liable for any damages resulting from members' and other customers' reliance on any translated document. The English version of any MasterCard document will take precedence over any translated version in any legal proceeding.
No assurances are given that the information provided herein is error-free. You acknowledge and agree that inaccuracies may be present. The information is provided to you on an "AS IS" basis for use at your own risk. MasterCard will not be responsible for any action you take as a result of this document.
MWMI
Date | Enhancement Type | Description |
---|---|---|
9/19/2014 | Updates |
|
10/26/2013 | Updates |
|
This document is intended to orient Service Partners and their developers seeking to integrate MasterPass as a checkout option for merchant's commerce sites or mobile application.
MasterPass is a service that enables consumers to store, manage and securely share their payment, shipping and rewards information with the websites and mobile apps they transact with. MasterPass supports checkout on full and mobile websites, as well as in-app purchases on Android™ and iOS™ apps.
The MasterPass user interface, or Lightbox, floats the MasterPass wallet interface on top of the Merchant's web page through illuminated overlays, and backgrounds dimmed to 0.7 opacity. This modern method allows a consumer to interact with their MasterPass digital wallet without having to leave the merchant's page. MasterPass Lightbox is built in a responsive design style allowing it to respond dynamically to the various screen sizes and orientations.
MasterPass supports the following displays:
At full screen, where the browser is set to 100% height and width, the overall Lightbox dimensions are 740 pixels (height) by 700 pixels (width). This is inclusive of the Lightbox header and footer. The interior Lightbox dimensions are 590 pixels (height) by 680 pixels (width). The interior Lightbox dimensions specify the content area within which the Partner can design (see screenshot below).
If the height of the browser is reduced so that the entire Lightbox has a height of 740 pixels and the width is maintained, the content container has the following dimensions: 530 pixels (height) by 680 pixels (width).
If the browser is set to 100% maximum width, but is less than 530 pixels in height (for the content container), vertical scrolling will appear.
If the browser is set to less than 680 pixels in width the Lightbox layout will change to accommodate small screen formats (i.e. phone, smaller tablets). There is a 320 pixel width threshold for the content container.
Within the .mobi experience, the header and footer are approximately 70 pixels high except for the iPhone 5/5S, which has a header and footer which are approximately 30 pixels high. The interior content area for mobile devices is content dependent. The initial view of content is based on the overall screen sizes. Content that does not fit within the initial view of content can be accessed by scrolling. There will not be a landscape view for mobile; only portrait will be supported.
Under certain conditions, such as when the consumer's browser does not support the Lightbox display (older browser), or if the merchant has not yet made coding changes to invoke the Lightbox display, or if the URL requesting the Lightbox display is different from the merchant specified origin URL, then MasterPass will render the wallet experience in full screen. This full screen wallet experience supports all functionality and design as that of the Lightbox display.
MasterPass is introducing new checkout options that offer merchants greater flexibility and control over the MasterPass checkout experience.
Merchant |
MasterPass |
Merchant |
||||||
---|---|---|---|---|---|---|---|---|
Experience |
Logs into Merchant |
Consumer Clicks |
Signs into Wallet |
Finalizes Payment Method/ Address |
Reviews/ Submits Order |
Confirms Order |
Receipt/ Thank You Page |
|
Standard Checkout |
Buy with MasterPass |
X |
X |
X |
(recommended) |
X |
||
Connected Checkout |
X |
Checkout |
X |
|
X* |
X |
*If applicable, advanced authentication, will be invoked after this step.
The flows below depict the Standard MasterPass Checkout flow with the Lightbox MasterPass UI. Merchants should use this flow for a non-recognized (guest) user.
'Connected Checkout" enables MasterPass merchants to provide a customized checkout experience to their consumers across all connected channels. In the connected checkout model, consumers who have paired their wallet with the merchant allow that merchant to retrieve the consumer's pre-checkout data (shipping, and other wallet information, without the actual card number without the consumer having to log in to their wallet. The actual PAN will be provided to the merchant only after the consumer logs in to their wallet (by entering only the wallet password). Data shared in connection with the "Connected Checkout" can only be used to implement checkout and must be destroyed immediately following the check-out experience. No data shared during the "Connected Checkout" experience may be retained after the checkout is completed. Adherence to MasterPass branding requirements is required. (for display of Wallet Partner logo and MasterPass logo near the pre-checkout information).
Connected checkout is supported by 3 components.
The consumer consents to 'pair' their wallet account with their account on the merchant side (consumer's merchant account), by agreeing to Connected Checkout. Pairing can happen during Checkout or outside of checkout on the merchant site/app. Pairing enables the consumers' MasterPass wallet data to be shared with the merchant during current and/or future visits to merchant app/site. This is accomplished by passing a Long Access token to the merchant. No cardholder data should be retained by the Merchant or Service Provider in between checkouts.
NOTE: Long Access token is a one-time use token. Each time a call using Long Access Token is made, a new Long Access token will be passed back to the merchant. This new Long Access token will then need to be stored, to be used the next time.
Pair with MasterPass Wallet during Checkout
In this experience, a consumer pairs their wallet with a merchant while performing checkout. The pairing process starts when a consumer clicks the 'Buy with MasterPass' button on the merchant site. This begins a set of exchanges that will bring the consumer through MasterPass and back out to the merchant again. If the consumer agrees to pair their wallet with the merchant, the consumer's pre-checkout data will be available to the merchant during subsequent checkouts without the consumer having to log in to their wallet. When checkout is completed, the consumer data must be immediately deleted.
Pair with MasterPass Wallet outside of a Checkout
In this experience, a consumer pairs their wallet with a merchant while not performing checkout e.g. account management. The pairing process starts when a consumer clicks the 'Connect with MasterPass' button on the merchant site. This begins a set of exchanges that will bring the consumer through MasterPass and back out to the merchant again. If the consumer agrees to pair their wallet with the merchant, the consumer's pre-checkout data will be available to the merchant during their subsequent checkouts without the consumer having to log in to their wallet. When checkout is completed, the consumer data must be immediately deleted.
Once the consumer has paired their wallet account with merchant account, when the consumer returns to the merchant site/app and logs in to their merchant account, the Merchant, through the Service Provider, submits the token to MasterPass to retrieve the consumer's up to date wallet information (card details without card number, addresses etc.). The merchant can then present this information to the consumer as part of their own experience, with the ability to streamline/personalize the consumer's experience during Pre-checkout. Consumers can then checkout easily. The actual PAN will be provided to the merchant only after the consumer logs in to their wallet (by entering the wallet password).
Data shared in connection with the "Return/Connected Checkout" can only be used for the express purposes permitted in the MasterPass Operating Rules and must be removed immediately following the check-out experience. No data shared during the "Return/Connected Checkout" experience may be retained after the checkout is completed. Service Providers are responsible for ensuring that merchants participating in MasterPass through the merchant by merchant model comply with this requirement.A consumer can 'unpair' the token or disconnect their current pairing consent any time, using MasterPass account management. This will prevent the merchant from accessing the consumer's wallet information going forward.
Enabling checkout with MasterPass on-behalf of your merchant site or mobile app is straightforward-here are the required activities for the Merchant by Merchant onboarding process
This process should be used if merchants will create their own accounts. Merchants will also be required to approve the checkout projects in this model. Step by step instructions can be found here.
Activity |
Actor |
Steps |
Environment |
---|---|---|---|
Service Provider |
Create Service Provider account |
||
Service Provider |
Add Developer to Service Provider Profile |
||
Merchant |
Create Merchant account, set shipping profile, rewards and advanced authentication |
||
Merchant |
Invite Service Provider to manage integration |
||
Developer |
Create MasterPass Developer account |
||
Create Developer Zone account |
|||
Generate developer's sandbox and production keys |
|||
Review sample code/SDK and design services integration |
|||
Request access to merchant's sandbox credentials |
|||
Merchant |
Approve and grant access to merchant's sandbox key |
||
Developer |
Use merchant's sandbox key to test against MasterPass sandbox environment |
Service Provider Engineering Environment |
|
Developer |
Request access to merchant's production credentials |
||
Merchant |
Approve and grant access to merchant's production key |
||
Developer |
Update MasterPass API endpoints, Consumer key, Callback URL and Private Key (p12), if different than Sandbox. |
Service Provider Production Environment |
The following accounts will be created during the onboarding process. Please use the following table to record the account information for future reference
Note: Email address must be unique for each account.
Account Type |
Details |
Account Info |
---|---|---|
Partner Portal - Service Provider Account |
Created by Service Provider business owner. This id should be used to login at https://masterpass.com/SP/Partner/Home Go here to create Service Provider account, invite developers, etc. |
Userid: __________ Email: ___________ |
Partner Portal - Service Provider Developer Account(s) |
Created when the Service Provider invites a developer. It's a system generated user id. This id should be used to login at https://masterpass.com/SP/Partner/Home Go here to create checkout project, get checkout project details etc. |
Userid: __________ Email: ___________ |
Developer Zone - Developer Account(s) |
Created by developer and is used for key exchange. This id should be used to login at https://developer.mastercard.com Go here to perform key exchange, download Sample Applications, integration guide etc. |
Userid: __________ Email: ___________ |
Merchant Portal - Merchant Account(s) |
A merchant account per merchant who will invite partner to integrate their system with MasterPass. This id should be used to login at https://masterpass.com/SP/Merchant/Home Go here to create merchant account, invite Service Provider, create shipping profiles, rewards, approve checkout projects etc. |
Userid: __________ Email: ___________ |
By the end of the integration, your site or mobile app should be able to:
Please note your implementation must satisfy all criteria in the Q/A checklist.
From the MasterPass Partner Portal, select the country - language from the dropdown and click the Create an Account button to start the registration process. You will be presented with a modal window, into which you will enter the invitation code. Please reach out to your MasterCard representative to obtain an invitation code that will grant you access and allow you to register within the partner portal. Follow the steps to create a Service Provider account.
At this point, you will have a Service Provider account created.
After account creation, you will add developers to your account. Click on Manage Setup and add developers to your Service Provider account. To get started, click the Start This Step button from the MasterPass Setup page.
Please forward this integration guide to each invited developer. Each developer will receive two invitation emails from MasterPass, indicating that he/she has been invited to handle the technical integration of MasterPass on-behalf of your company. This integration guide will guide the developer through the integration process.
Your developer will navigate to the MasterPass portal and complete sign-up. He/she would then go to MasterCard Developer Zone to generate API keys.
From the MasterPass Merchant Portal, select the country - language from the dropdown and click the Create an Account button to start the registration process. You will be presented with a modal window, into which you will enter the invitation code. After entering the invitation code, you will be presented with the option to select the registration type. Select Merchant to continue with the registration process as shown in screen shots below.
After the merchant account has been created, select "Shipping Locations" to manage your shipping options. Merchants can have multiple shipping profiles and can also set a preferred shipping profile option.
Select "Reward Program" to enter details about your reward/ loyalty program. The name of the Reward Program and Logo provided will be displayed to the consumer during checkout. Here are the field details
If available, select "Authentication Settings" to enable 3DS Authentication. Where available, 3DS may be opted into for MasterCard, Maestro, and Visa only.
If 3DS is available to your country, you may enable it by completing the Authentication Settings section. If 3DS is not available to you, you will not see the Authentication Settings tab.
Select "Advanced Checkout" on the Authentication Settings page, which means that 3DS will be run for all checkout transactions for the appropriate card brand. To enable 3DS for your transactions, you will need to supply the details of your 3DS-enabled Acquirer accounts. To add accounts, click "Manage Accounts" and then click "Add Merchant Acquirer"
Provide the details requested for each of your MasterCard, Maestro, and/or Visa accounts.
Note: Initial setup for each new acquirer and merchant account normally takes 5 business days. Currently, 3DS can only be tested in production (not in sandbox).
If you enable your account up for 3DS, you will have the option to "downgrade" the transaction to Basic at time of checkout by setting the value of auth_level parameter to "basic"
Sign in to your merchant's account from the MasterPass Merchant Portal. From the landing page, you will add developers. Start the "Add Developers" process and select "A third party platform provider". Then pick the Service Provider from the drop down list.
The Service Provider's Developer will receive invitation emails from MasterPass, indicating that he/she has been selected to handle the technical integration of MasterPass Services on-behalf of the Merchant. The integration guide will guide the developer through the integration process.
Developers invited to integrate MasterPass on behalf of a merchant will manage their integration activities through two portals:
Developers will use the MasterPass Merchant Portal to request, and access merchant-specific integration credentials, which will be used when interacting with the MasterPass web services. After the Service Provider invites you as a developer, you should have received your MasterPass Developer credentials in two emails from MasterPass.
Developers invited to integrate MasterPass on behalf of a merchant/service provider will use MasterCard Developer Zone to view integration documentation and generate developer keys. To create a Developer Zone account, visit Developer Zone and click Register. After submitting the form, be sure to activate the account using the confirmation email.
After creating your account, you will need to generate two sets of API keys (one each for the sandbox and production environments). To make keys easy to distinguish, it's recommended to prefix sandbox keys with "SBX_" and production keys with "PRD_".
To create a Sandbox key, click My Account, then My Dashboard.
On the My Dashboard page, click My Keys button and then click on Add a Key button.
In order to get an API Key, you need to supply a PEM encoded Certificate Request File. You may use a tool of your choice, such as "openssl" or Java's "keytool" to generate this CSR, or you may use the CSR generation tool on the developer zone portal. Click here to see instructions for using CSR generation tool.
Complete the form, select Sandbox for Environment, and click
Submit.
You will have Sandbox Key ID at this point.
To create a Production API key, return to My Dashboard and click on My Keys. Then click on Add a Key and make sure you select Production environment. Complete the form and click Submit.
At this point, developers will have Sandbox and Production Key ID. These IDs will be used when submitting a checkout project to the merchant for approval.
Note: Keys expire after 1 year before which they should be renewed by initiating the Developer Zone Key Renewal process. Notifications at 30, 15 and 1 day prior to key expiration will be sent to the email address associated with the Developer Zone account. Your integration will stop working if the keys are expired.
At this point, developers should begin developing their own implementation. Sample Applications for .NET (C#), Java, PHP and Ruby are available for download on Developer Zone.
Prior to allowing the developer's code to interact with the MasterPass service (on-behalf of a merchant) the merchant must approve the checkout project created by the developer. The developer will make two separate approval requests. The first request is to grant the developer access to credentials that will enable his/her code to transact with the MasterPass sandbox environment on-behalf of the merchant. The sandbox environment does not contain real consumer data. The second is for production credentials, which will enable real transactions.
Developers will use MasterPass Merchant Portal to request, and access merchant-specific integration credentials, which will be used when interacting with the MasterPass services. The credentials are requested by submitting a checkout project.
To get started, sign into the MasterPass Merchant Portal. Under Manage Development, click Checkout Projects -> Create New Project and complete the New Project creation wizard.
Select applicable Merchant from the drop-down.
Enter Project Name, Project Description.
Enter branding elements for the merchant (Merchant Name, Logo), domain-level URL that consumers will be redirected from in the sandbox and production enviornments. Merchant Name will be displayed if no logo is provided. The recommended logo dimensions for a website project are 100X60 pixels; the recommended logo dimensions for a mobile project is 80X30 pixels.
Enter the sandbox and production Key IDs that were created on from MasterCard Developer Zone.
To submit the project for sandbox approval, click Submit.
After the Developer submits the request for sandbox credentials, the Merchant will get an email notification. The Merchant will log on to the MasterPass Merchant Portal, review the branding and provide approval.
After clicking Approval Requests on the navigation bar, the user will see a list of open requests. Click View Details.
Merchant should ensure that the merchant name, URL and logo are correct by clicking on View Details to approve it. Please note that the consumer facing UI will be the new MasterPass Lightbox user interface, and the branding shown will be different in the end user experience. The MasterPass interface in this step is illustrative only and not representative of actual end consumer user interface.
After reviewing these branding elements and closing the modal window, the user will be presented with the option to either Approve or Reject the project. If rejected, a reason must be provided, and the deveoper will be allowed to modify the entry and resubmit.
After approval has been granted by the Merchant, the Developer will receive an email notification that changes have been approved. The Developer will sign into the MasterPass Merchant Portal and will note the Sandbox Consumer Key associated with the checkout project. Click the View Branding link to view the Checkout Identifier. Please note MasterPass UI is illustrative only. Please refer to Developer Zone for sample code and SDKs.
(Please note MasterPass UI is illustrative only and is not representative of actual consumer UI). Make a note of the following values as they will be used in the code to integrate with MasterPass web services:
Once the application has been tested against sandbox, the Developer will request the Merchant's production credential. This is done by submitting the checkout project created in Step 5 and submitting it again to the merchant for approval.
After the Developer submits request for production credentials, the Merchant will get an email notification. The Merchant will log on to the MasterPass merchant portal, click on Approval Request, review the branding and provide approval (similar to step 6).
After merchant approval, the developer will receive email containing the merchant's production Consumer Key, production callback URL and the Checkout Identifier. Prior to production deployment, update your code with the MasterPass production endpoint, merchant's production Consumer Key, checkout identifier, production callback URL and the keystore if different than Sandbox. The last step is to deploy your code to production. You're all done!
Note: For more details on the specific configuration parameters, please refer to the FAQ section at https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+FAQs and look for the question, "What are the various parameters I need, to call MasterPass services and where do I get them from?"
Note: Signature base string, request and response samples are available in the Appendix. Sample code for all the steps in the integration process is available on Developer Zone
Lightbox integration is required to launch MasterPass user interface. In order to invoke the Lightbox, merchants will need to include the following scripts on the page they implementing ' Buy with MasterPass' or 'Connect with MasterPass' buttons:
The following steps are necessary to integrate a standard MasterPass checkout. For further information, click on each step of the process.
Within a script tag the merchant must invoke the checkoutButton method with the required parameters.
<script type="text/javascript" language="Javascript"> MasterPass.client.checkout({ "requestToken":"insert_request_token_here", "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm", "merchantCheckoutId":"insert_checkout_id_here", "allowedCardTypes":["master,amex,diners,discover,maestro,visa"], "version":"v6" }); </script>
Required parameters are:
Lightbox parameter details can be found here.
Once a checkout completes, MasterPass will return context to the merchant. This can be done via:
"http://www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc">www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc
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; }
Note: For Pairing to occur, the merchant must have a way of identifying consumers on the merchant site prior to requesting pairing
The following steps are necessary to establish a connection to a consumer's wallet outside of checkout flow. For further information, click on each step of the process. .
Consumers can pair their MasterPass wallet with merchant outside of checkout by clicking on the "Connect With MasterPass button." Merchants can display the "Connect with MasterPass" button anywhere on their site except on checkout pages or pages where payment is initiated. to enable pairing without doing a checkout.
Within a script the merchant must invoke the connect method with the required parameters.
<script type="text/javascript" language="Javascript"> MasterPass.client.connect({ "pairingRequestToken":"de7647ac630b50f32f5c9addac122614a727ba52f", "callbackUrl":"http://www.somemerchant.com/pairingcomplete.htm", "merchantCheckoutId":"insert_checkout_id_here", "requestedDataTypes":"[REWARD_PROGRAM, ADDRESS, PROFILE, CARD]", "requestPairing":true "version":"v6" }); </script>
Required parameters are:
Lightbox parameter details can be found here.
Pairing without checkout Callback
Once a pairing flow completes, MasterPass will return context to the merchant. This can be done via a callback URL or a javascript call back method. If you wish to use the callback method, "failureCallback" and "successCallback" parameters must be set when invoking MasterPass Lightbox.
http://www.somemerchant.com/pairingcomplete.htm?status=success&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13&pairing_token=886116426bdb8cd83deed1fbe73df21646016b1f
function onSuccessfulPairing(data) { document.getElementById('pairingToken').value=data.pairing_token; document.getElementById('pairingVerifer').value=data.pairing_verifier; }
The following steps are necessary to establish a connection to a consumer's wallet during a checkout. For further information, click on each step of the process:
*The request token service to get checkout request token and pairing request token is the same service call but needs to be differentiated by the Service Provider.
**The access token service will be called twice, one for long access token (used to retrieve pre-checkout data) and other to retrieve checkout data for current transaction.
Within a script tag the merchant must invoke the checkout method with the required parameters. Here is an example
<script type="text/javascript" language="Javascript"> MasterPass.client.checkout({ "requestToken":"de4847ac630b50f32f5c9ddac122614a727ba52f", "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm", "pairingRequestToken":"de7647ac630b50f32f5c9addac122614a727ba52f", "requestedDataTypes":"[REWARD_PROGRAM, ADDRESS, PROFILE, CARD]", "merchantCheckoutId":"a4d6x6r6zhak9hvkkkl091hvofxxmat4y", "allowedCardTypes":["master", "amex","discover"], "requestPairing":true "version":"v6" }); </script>
Required parameters are:
Lightbox parameter details can be found here.
Once a checkout and pairing completes, MasterPass will return context to the merchant. This can be done via a callback URL or a javascript call back method. If you wish to use the callback method, "failureCallback" and "successCallback" parameters must be set when invoking MasterPass Lightbox.
http://www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F10706241%3Fwallet%3Dphw&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530
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; document.getElementById('pairingToken').value=data.pairing_token; document.getElementById('pairingVerifer').value=data.pairing_verifier; }
The following steps are necessary to integrate a connected checkout flow. For further information, click on each step of the process..
Connected checkout can be used after a user has paired their wallet. The merchant will pass in selections based on the precheckout data for a streamlined checkout experience.
Within a script tag the merchant must invoke the checkout method with the required parameters.
<script type="text/javascript" language="Javascript"> MasterPass.client.checkoutButton({ "requestToken":"insert_request_token_here", "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm", "merchantCheckoutId":"insert_checkout_id_here", "cardId":" insert_card_id_here ", "shippingId":"insert_shipping_address_id_here", "precheckoutTransactionId":"insert_prechechout_txn_id_here", "walletName":"insert_wallet_name_here", "consumerWalletId":"insert_consumer_walletid_here",
"version":"v6" }); </script>
Required parameters are:
Lightbox parameter details can be found here
Once a checkout completes, MasterPass will return context to the merchant. This can be done via a callback URL or a javascript call back method. If you wish to use the callback method, "failureCallback" and "successCallback" parameters must be set when invoking MasterPass Lightbox. Here are the examples
http://www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F10706241%3Fwallet%3Dphw&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498
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; }
This should be executed when a consumer clicks "Buy with MasterPass" button or "Connect with MasterPass" button on the merchant's site/app.
For Pairing during checkout, this service will need to be called twice:
Request and response parameter details can be found here
https://sandbox.api.mastercard.com/oauth/consumer/v1/request_token
https://api.mastercard.com/oauth/consumer/v1/request_token
Merchants must call the Shopping Cart service before invoking the MasterPass UI for checkout. This enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout.
Shopping cart request has an optional OriginUrl field, if the merchant sets this, it will remove the need to call the merchant initialization service before displaying the Lightbox. Request and response parameter details can be found here
Note: The product description needs to be HTML encoded.
https://sandbox.api.mastercard.com/masterpass/v6/shopping-cart
https://api.mastercard.com/masterpass/v6/shopping-cart
This service is used to secure Lightbox connections between merchant and MasterPass This service requires a request token (OAuthToken). This service call should be used when shopping cart service is not called e.g. pairing outside of checkout flow.
Request and response parameter details can be found here.
https://sandbox.api.mastercard.com/masterpass/v6/merchant-initialization
https://api.mastercard.com/masterpass/v6/merchant-initialization
Next step is to exchange a Request token for an Access token from the MasterPass service. For Pairing during checkout, this service will need to be called twice: once for requesting the checkout access token which is used to retrieve checkout data; and one for requesting the long access token which is used to retrieve pre-checkout data. You will use the Request Token (oauth_token) and Verifier (oauth_verifier) from the merchant callback to get an access token. Request and response parameter details can be found here.
https://sandbox.api.mastercard.com/oauth/consumer/v1/access_token
https://api.mastercard.com/oauth/consumer/v1/access_token
MasterPass provides merchants with the ability to request a paired consumer's data (card alias, shipping addresses, loyalty program, and profile information) prior to the actual MasterPass checkout. This gives the merchant the ability to provide the consumer the opportunity to pre-select their checkout options before completing the checkout.
If for any reason the precheckout call gets rejected at MasterPass (merchant requests data that the consumer did not originally consent to, if the pairing has been deleted by the user, if the Long Access token has expired, etc.) the merchant has to request pairing again.
Note: This is not required for standard checkout.
Request and response parameter details can be found here.
https://sandbox.api.mastercard.com/masterpass/v6/precheckout
https://api.mastercard.com/masterpass/v6/precheckout
Now you will use the Checkout Resource URL request parameter (checkout_resource_url) received from the callback URL to retrieve consumer's payment, shipping address, reward and 3DS information from MasterPass. Request and response parameter details can be found here.
Please note that MasterPass performs a CVC/CVV check at card enrollment. However, in accordance with PCI standards, CVC2/CVV2 data is not persisted, and will not be provided to the merchant. As the card data has been validated and securely stored by MasterPass, merchants must not require CVC/CVV entry from a consumer checking out with MasterPass.
Note: In cases where, prior to submitting their order, the cardholder chooses to replace the payment details provided by MasterPass with different, manually entered payment details, Merchants should ask the cardholder to enter CVV2/CVC2/CID as they would in the normal course and should not pass the wallet indicator flag to the acquirer. In this case, the transaction is no longer considered to be a MasterPass transaction. Checkout Postback is still required. It is recommended not to allow consumers to change their card details after returning from MasterPass.
In accordance with MasterCard bulletin Global 550-Identification of PayPass Transactions, a 3 byte wallet Indicator Flag (WalletID xml element in the checkout xml will be part of the output returned by this request. This value must be passed to your acquiring bank, and will indicate that the customer's payment details were provided by the MasterPass service, rather than being manually entered. You many need to work with your payment provider (acquirer, payment gateway, etc.) to understand how best to handle this data element. In the event, your acquirer has not completed implementation of this bulletin, your transactions will continue to process as-is. Please contact your MasterCard representative to get the bulletin.
This project created the following new message elements in Dual Message Authorization, Dual Message Clearing, and the Single Message System to carry this identifier:
Note: This is a mandatory step.
The final step of a MasterPass transaction is a service call from the service provider to MasterPass, communicating the result of the transaction (success or failure). Abandoned transactions do not need to be reported. Please note that the <TransactionId> value should be the value from the <TransactionId> element of the Checkout XML returned in the Checkout request.
Request and response parameter details can be found here.
The following fields are passed in the postback service call:
https://sandbox.api.mastercard.com/masterpass/v6/transaction
https://api.mastercard.com/masterpass/v6/transaction
Your Android or iOS application should invoke a backend service to initiate the OAuth authorization. On the native application side, most of the work involves connecting to your backend services.
The basic process is as follows:
The MasterPass acceptance mark and checkout button image URLs can be found below. To ensure the best consumer experience, the checkout button should be placed at the beginning of the checkout experience, prior to the collection of shipping and billing information.
To minimize the impact of future branding updates, please use the country specific link to the images on the checkout page rather than downloading them and hosting the images locally. In order to successfully integrate with MasterPass and enable successful checkout by an end-user consumer via the service, the 'Buy with MasterPass' checkout button must be integrated on the merchant website and displayed as noted in the MasterPass Branding Requirements document available on MasterCard developer zone.
The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code (ISO 3166-and Button as shown below: Base URL/Language/Country/Image File Name
Base URL: https://www.mastercard.com/mc_us/wallet/img/
Note: The list of language/country folders can be found at https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+FAQs under the question, "Which countries and locales are currently supported to link 'Buy with MasterPass' images?"
Below is an example of how a Merchant can include the checkout button.
<div "MasterPassBtnExample"> <a href="/exampleRedirect"> <imgsrc="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png" alt="Checkout with MasterPass Button Example" /> </a> </div>
/mcpp_wllt_btn_chk_147x034px.png
/mcpp_wllt_btn_chk_160x037px.png
/mcpp_wllt_btn_chk_166x038px.png
/mcpp_wllt_btn_chk_180x042px.png
/mcpp_wllt_btn_chk_147x034px.gif
/mcpp_wllt_btn_chk_160x037px.gif
/mcpp_wllt_btn_chk_166x038px.gif
/mcpp_wllt_btn_chk_180x042px.gif
/mp_mc_acc_023px_gif.gif
/mp_mc_acc_030px_gif.gif
/mp_mc_acc_034px_gif.gif
/mp_mc_acc_038px_gif.gif
/mp_mc_acc_050px_gif.gif
/mp_mc_acc_065px_gif.gif
/mp_mc_acc_113px_gif.gif
/mcpp_wllt_btn_chk_290x068px.png
/mcpp_wllt_btn_chk_317x074px.png
/mcpp_wllt_btn_chk_326x076px.png
/mcpp_wllt_btn_chk_360x084px.png
/mcpp_wllt_btn_chk_290x068px.gif
/mcpp_wllt_btn_chk_317x074px.gif
/mcpp_wllt_btn_chk_326x076px.gif
/mcpp_wllt_btn_chk_360x084px.gif
/mp_acc_046px_gif.gif
/mp_acc_060px_gif.gif
/mp_acc_068px_gif.gif
/mp_acc_076px_gif.gif
//mp_acc_100px_gif.gif
/mp_acc_130px_gif.gif
/mp_acc_226px_gif.gif
Here are a few examples
US English URL:
https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png
Canada French URL:
https://www.mastercard.com/mc_us/wallet/img/fr/CA/mcpp_wllt_btn_chk_147x034px.png
This button is used to initiate Pairing outside of a checkout.
The MasterPass connect button image URLs can be found below.
To minimize the impact of future branding updates, please use the country specific link to the images on the checkout page rather than downloading them and hosting the images locally. In order to successfully integrate with MasterPass and enable successful connection by an end-user consumer via the service, the "Connect with MasterPass" button must be integrated on the merchant website and displayed as noted in the MasterPass Branding Requirements document available on MasterCard developer zone.
The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code (ISO 3166-and Button as shown below: Base URL/Language/Country/Image File Name
Base URL: https://www.mastercard.com/mc_us/wallet/img/.
US English URL - Connect with MasterPass Button:
https://www.mastercard.com/mc_us/wallet/img/en/US/mp_connect_with_button_126px.png
Canada French URL - Connect Button:
https://www.mastercard.com/mc_us/wallet/img/fr/CA/mp_connect_with_button_034px.png
Note: The list of language/country folders can be found at https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+FAQs under the question, "Which countries and locales are currently supported to link 'Connect with MasterPass' images?"
Below is an example of how a Merchant can include the Connect with MasterPass button.
<div "MasterPassConnectBtnExample"> <a href="/exampleRedirect"> <img src="https://www.masterpass.com/lightbox/Switch/integration/MasterPass.connect.png"alt="Connect with MasterPass Button Example" /> </a> </div>
/mp_connect_with_button_034px.png
/mp_connect_with_button_037px.png
/mp_connect_with_button_038px.png
/mp_connect_with_button_042px.png
/mp_connect_with_button_068px.png
/mp_connect_with_button_074px.png
/mp_connect_with_button_126px.png
In addition to the MasterPass checkout button and acceptance mark, MasterPass also requires merchants to provide a link to "Learn More" page which can be used by the consumers to get additional information about MasterPass. It is recommended that you place the link in close proximity to the "Buy with MasterPass" button.
"Learn More" page is available in multiple languages and can be accessed from the following link. For the list of all available languages, please refer to FAQs on developer zone
English - http://www.mastercard.com/mc_us/wallet/learnmore/en
Swedish - http://www.mastercard.com/mc_us/wallet/learnmore/se
French - http://www.mastercard.com/mc_us/wallet/learnmore/fr
Italian - http://www.mastercard.com/mc_us/wallet/learnmore/it
Spanish - http://www.mastercard.com/mc_us/wallet/learnmore/es
Please refer to the FAQs for a list of all available countries at https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+FAQs under the question, "Which languages are currently available for use with the MasterPass 'Learn More' page?"
In order to access the necessary information to test in the sandbox environment, you must submit an approval request to the merchant as explained earlier in the guide. Testing can be conducted in the sandbox environment, using the test consumer account. Your code must gracefully handle the error states and scenarios listed below.
Note: You cannot add cards to a sandbox account. Only shipping addresses can be added to sandbox accounts.
Consumer Account (Sandbox) Do not modify this shared account |
|||
---|---|---|---|
Test Account 1 |
|||
Login Email |
Password |
abc123 |
|
Answer to Security Question |
Pets Name: fido |
||
Test Account 2 |
|||
Login Email |
Password |
abc123 |
|
Answer to Security Question |
Pets Name: fido |
Use the "remember me" and "remember this device" options when
testing so that you don't have to rekey the entire test account information every
time you login to MasterPass.
Once you are redirected to the sandbox environment, select MasterPass wallet to sign-in to Sandbox Consumer Wallet Account.
If you get "Error 400" when calling MasterPass web services
If you get "Error 401" when calling MasterPass web services
If you get "Error 403 - Forbidden" when calling MasterPass services
If you get "Error 500" when calling MasterPass web services
Please refer to the FAQs at https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+FAQs.
If you have any questions or comments relating to MasterPass integration, please contact us at merchant_support@masterpass.com.
O = Optional; R = Required; A = Automatically populated
Parameter name |
Data type |
Card security |
Checkout |
Connect |
Description |
---|---|---|---|---|---|
allowedCardTypes |
string[] |
O |
This parameter restricts the payment methods that may be selected based on card brand. Omit this parameter to allow all payment methods. Here are the valid values for different card types MasterCard: master Maestro: maestro American Express: amex Discover: discover Diners: diners Visa: visa |
||
loyaltyEnabled |
bool |
O |
This parameter defines if the merchant is requesting consumer's loyalty details from MasterPass for the transaction. Valid values are True or False. |
||
shippingLocationProfile |
string[] |
O |
This parameter defines Merchant's Shipping Profile(s) for that they set in their account. |
||
callbackUrl |
string |
O |
O |
O |
This defines the base URL to which the browser is redirected to upon successful or failed completion of the flow if there is no appropriate callback function available. |
cardId |
string |
O |
Required for connected checkout. Set to a valid payment card ID. |
||
failureCallback |
function |
O |
O |
O |
This defines the function to be called when the flow ends in failure. Refer SDK for more examples |
loyaltyId |
string |
O |
Optional for connected checkout. Set to a valid loyalty card ID. |
||
merchantCheckoutId |
string |
R |
R |
R |
This is the checkout identifier which is used to identify the merchant and their checkout branding. |
precheckoutTransactionId |
string |
R |
Helps the wallet identify the wallet account for which precheckout data is provided. MasterPass includes this parameter in the checkout xml for connected checkout |
||
requestBasicCheckout |
bool |
O |
Set to "true" to disable step-up authentication (advanced checkout) during any checkout flow. The default is "false". |
||
requestedDataTypes |
string[] |
O |
R |
This indicates the types of data being requested for pairing. Possible values include "PROFILE", "CARD", "ADDRESS", and "REWARD_PROGRAM". "PROFILE" and "CARD" are mandatory data types. Refer to precheckout data xml to get details of these data types. Refer to precheckout data xml to get details of these data types. This parameter is required when requestPairing is "true". |
|
requestPairing |
bool |
O |
A |
This indicates that the user is being asked to enable connected checkout. It is automatically set to "true" for the "Connect" flow. The default for other flows is "false". |
|
requestToken |
string |
R |
R |
R |
This is an OAuth token. |
pairingRequestToken |
string |
O |
R |
This is an OAuth token. |
|
suppressShippingAddressEnable |
Bool |
O |
When set to "True" shipping address screen is not displayed to consumer. When set to "false", shipping address are displayed and consumer can select. |
||
shippingId |
string |
O |
Optional for connected checkout. Set to a valid shipping destination ID. |
||
walletName |
string |
R |
Required for connected checkout to uniquely identify wallet name |
||
consumerWalletId |
string |
R |
Required for connected checkout to uniquely identify consumer |
||
successCallback |
function |
O |
O |
O |
This defines the function to be called when the flow ends in success. |
request_token Request |
request_token Response |
|
---|---|---|
oauth_callback |
X |
|
oauth_signature |
X |
|
oauth_version |
X |
|
oauth_nonce |
X |
|
oauth_signature_method |
X |
|
oauth_consumer_key |
X |
|
oauth_timestamp |
X |
|
realm |
X |
|
oauth_token |
X |
|
oauth_callback_confirmed |
X |
|
oauth_expires_in |
X |
|
oauth_token_secret |
X |
|
xoauth_request_auth_url |
X |
Request Token-Request |
Description |
Possible Values |
|
---|---|---|---|
Signature Base String Authorization Header |
oauth_callback |
Endpoint that will handle the transition from the wallet site to the merchant checkout page |
Variable |
oauth_signature |
RSA/SHA1 signature generated from the signature base string |
Variable |
|
oauth_version |
oAuth version |
1.0 |
|
oauth_nonce |
Unique alphanumeric string generated from code |
Variable |
|
oauth_signature_method |
oAuth signature method. |
RSA-SHA1 |
|
oauth_consumer_key |
Consumer Key generated when creating a checkout project on MasterPass Merchant portal |
Variable |
|
oauth_timestamp |
Current timestamp |
Variable |
|
realm |
Used to differentiate between our mobile and full site. Currently not used. |
eWallet |
|
Request Token-Response |
Description |
Possible Values |
|
Oauth Token |
oauth_token |
oauth_token is sent in the signature base string, authorization header and redirect URL |
Variable |
Request Token |
oauth_callback_confirmed |
Variable |
|
oauth_expires_in |
Time the Request Token expires in seconds |
Variable |
|
oauth_token_secret |
Oauth Secret |
Variable |
|
xoauth_request_auth_url |
Authorize URL |
Variable |
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer%2Fv1%2Frequest_token&oauth_callback%3Dhttp%253A%252F%252Fprojectabc.com%252Fmerchant%252FCallback.jsp%26oauth_consumer_key%3DZGho8Df8vqW-IpGCIu559HYriL093IBXdJeKavp4dce9db2a%25216464586653467358724b616c74475445443349466a413d3d%26oauth_nonce%3D1143452272881219%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1339612030%26oauth_version%3D1.0
POST /oauth/consumer/v1/request_token HTTP/1.1Authorization: OAuth oauth_callback="http%3A%2F%2Fprojectabc.com%2Fmerchant%2FCallback.jsp",oauth_signature="pzNogGtgShe16%2FwhP4CsTRXkgJ1mv%2FKm6do5ZVi6doKzAJZ0m8QqhiERi5lRuphdyUkhW8LKdUL1TetPdxm32Vtr%2BQGF6n6IBjr8dGcyYmfaLyAYVhF%2Fx5oQhUDVpdXIc10dJ0miUwZPbJ1QopN3ibeOzvgNxhEiHYKVnpvYEhc%3D",oauth_version="1.0",oauth_nonce="1143452272881219",oauth_signature_method="RSA-SHA1",oauth_consumer_key="ZGho8Df8vqW-IpGCIu559HYriL093IBXdJeKavp4dce9db2a%216464586653467358724b616c74475445443349466a413d3d",oauth_timestamp="1339612030",realm="eWallet"
oauth_callback_confirmed=true&oauth_expires_in=900&oauth_token=a02c5c5c1a128c2cebc650ea9aa3dfb7&oauth_token_secret=c2daaf0888779d82bd63524159bee91f&xoauth_request_auth_url=https%3A%2F%2Fsandbox.masterpass.com%2Fonline%2FCheckout%2FAuthorize
Merchant Initialization resource Request |
Merchant Initialization Resource Response |
|
---|---|---|
oauth_signature |
X |
|
oauth_version |
X |
|
oauth_nonce |
X |
|
oauth_signature_method |
X |
|
oauth_consumer_key |
X |
|
oauth_timestamp |
X |
|
realm |
X |
|
oauth_body_hash |
X |
|
oauth_token |
X |
|
Merchant Initialization |
X |
Merchant Initialization Resource-Request |
Description |
Possible Values |
|
---|---|---|---|
Signature Base String Authorization Header |
oauth_signature |
RSA/SHA1 signature generated from the signature base string |
Variable |
oauth_version |
Oauth version. |
1.0 |
|
oauth_nonce |
Unique alphanumeric string generated from code |
Variable |
|
oauth_signature_method |
oauth signature method. |
RSA-SHA1 |
|
oauth_consumer_key |
Consumer Key generated when creating a checkout project on MasterPass Merchant portal |
Variable |
|
oauth_timestamp |
Current timestamp |
Variable |
|
oauth_token |
Request token |
Variable |
|
Merchant_Initialization _origin_url |
URL of the page that will initialize the Lightbox |
||
Merchant Initialization Resource-Response |
Description |
Possible Values |
|
Oauth Token |
oauth_token |
oauth_token is sent in the request |
Variable |
PreCheckout TransactionID |
PreCheckout TransactionID |
PreCheckoutTransactionID sent in the request only for Connected checkout. |
Variable |
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%merchantinitialization&oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4-B4263CB5A305%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380049711%26oauth_version%3D1.0
POST /masterpass/v6/merchant-initialization HTTP/1.1Authorization: OAuth realm="eWallet",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_signature_method="RSA-SHA1",oauth_nonce="DEAEB1CD-CA03-405D-A7B4-B4263CB5A305",oauth_timestamp="1380049711",oauth_version="1.0",oauth_body_hash="8K9uhveZjVdZW8AIYiXpR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zravb02oqTrVQH3Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D" XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="MerchantInitializationRequest" type="MerchantInitializationRequest" /> <xs:complexType name="MerchantInitializationRequest"> <xs:sequence> <xs:element name="OAuthToken" type="xs:string" /> <xs:element name="PreCheckoutTransactionId" type="xs:string" maxOccurs="1" minOccurs="0" /> <xs:element name="OriginUrl" type="xs:string" /> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any" /> </xs:sequence> <xs:anyAttribute /> </xs:complexType> </xs:schema>
<MerchantInitializationRequest> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> <OriginUrl>https://somemerchant.com</OriginUrl> </MerchantInitializationRequest>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="MerchantInitializationResponse" type="MerchantInitializationResponse"/> <xs:complexType name="MerchantInitializationResponse"> <xs:sequence> <xs:element name="OAuthToken" type="xs:string"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any" /> </xs:sequence> <xs:anyAttribute /> </xs:complexType> </xs:schema>
<MerchantInitializationResponse> <OAuthToken>4c7b34cc63a68282bba77a4b34f0192fcb2268fb</OAuthToken> </MerchantInitializationResponse>
MerchantInitializationRequest XML |
Element |
Description |
Type |
Min-Max |
---|---|---|---|---|
MerchantInitializationRequest |
Root Element |
XML |
- |
|
MerchantInitializationRequest |
OAuthToken |
Request Token (oauth_token) returned by call to the request_token API |
- |
|
PreCheckoutTransactionID |
Identifies pre-checkout transaction. Returned from get pre-checkout data call; Optional |
string |
NA |
|
OriginUrl |
Identifies the URL of the page that will initialize the Lightbox. |
string |
NA |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
||
MerchantInitializationResponse XML |
Element |
Description |
Type |
Min-Max |
OAuthToken |
Request Token (oauth_token) returned by call to the request_token API |
XML |
- |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
Starting with API v6, all schema container elements contain a new optional element named "ExtensionPoint". These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of "xs:any", meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an ExtensionPoint element, beyond any that may be defined by MasterPass in the future with a separate schema. Any such extensions will be optional. Further, only authorized schemas will be allowed inside ExtensionPoint elements, and any unknown elements will be dropped by MasterPass.
<ExtensionPoint> <s:SampleExtension xmlns:s=”https://www.masterpass.com/location/of/example/ns”> <s:SampleField>Sample Value</s:SampleField> </s:SampleExtension> <f:AnotherExampleExtension xmlns:f=”https://www.masterpass.com/location/of/example2/ns> <f:SampleContainer> <f:AnotherSampleField>Sample Value</f:AnotherSampleField> </f:SampleContainer> </f:AnotherExampleExtension> </ExtensionPoint>
Shopping Cart Request |
Shopping Cart Response |
|
---|---|---|
oauth_signature |
X |
|
oauth_version |
X |
|
oauth_nonce |
X |
|
oauth_signature_method |
X |
|
oauth_consumer_key |
X |
|
oauth_timestamp |
X |
|
oauth_body_hash |
X |
|
oauth_token |
X |
X |
Shopping Cart Request XML |
X |
|
Shopping Cart Response XML |
X |
Shopping Cart-Request |
Description |
Possible Values |
|
---|---|---|---|
Signature Base String Authorization Header |
oauth_signature |
RSA/SHA1 signature generated from the signature base string |
Variable |
oauth_version |
Oauth version |
1.0 |
|
oauth_nonce |
Unique alphanumeric string generated from code |
Variable |
|
oauth_signature_method |
oauth signature method |
RSA-SHA1 |
|
oauth_consumer_key |
Consumer Key generated when creating a checkout project on MasterPass Merchant portal |
Variable |
|
oauth_timestamp |
Current timestamp |
Variable |
|
oauth_body_hash |
SHA1 hash of the message body |
Variable |
|
Oauth Token |
oauth_token |
oauth_token is sent in the signature base string, authorization header and redirect URL |
Variable |
Transfer XML Strings |
Shopping Cart Request XML |
Merchant Shopping Cart details |
|
Shopping Cart-Response |
Description |
Possible Values |
|
Oauth Token |
oauth_token |
oauth_token is sent in the signature base string, authorization header and redirect URL |
Variable |
Transfer XML Strings |
Shopping Cart Response XML |
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fshopping-cart &oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4-B4263CB5A305%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380049711%26oauth_version%3D1.0
POST /masterpass/v6/shopping-cart HTTP/1.1 Authorization: OAuth realm="eWallet",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_signature_method="RSA-SHA1",oauth_nonce="DEAEB1CD-CA03-405D-A7B4-B4263CB5A305",oauth_timestamp="1380049711",oauth_version="1.0",oauth_body_hash="8K9uhveZjVdZW8AIYiXpR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zravb02oqTrVQH3Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="ShoppingCartRequest" type="ShoppingCartRequest" /> <xs:complexType name="ShoppingCartRequest"> <xs:sequence> <xs:element name="OAuthToken" type="xs:string" /> <xs:element name="ShoppingCart" type="ShoppingCart" /> <xs:element name="OriginUrl" type="xs:string" minOccurs="0" /> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="ShoppingCart"> <xs:sequence> <!-- CurrencyCode is defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars. All Monetary Values will be modified by the CurrencyCode. For example a Monetary Value of 11900 combined with a CurrencyCode of USD will be handled at $119.00. --> <xs:element name="CurrencyCode" type="xs:string" /> <xs:element name="Subtotal" type="xs:long" /> <xs:element name="ShoppingCartItem" type="ShoppingCartItem" minOccurs="0" maxOccurs="unbounded" /> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="ShoppingCartItem"> <xs:sequence> <xs:element name="Description" type="xs:string" /> <xs:element name="Quantity" type="xs:long" /> <xs:element name="Value" type="xs:long" /> <xs:element name="ImageURL" type="xs:string" minOccurs="0" /> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any" /> </xs:sequence> <xs:anyAttribute/> </xs:complexType> </xs:schema>
ShoppingCartRequest |
Element |
Description |
Type |
Min-Max |
---|---|---|---|---|
|
OAuthToken |
Request Token (oauth_token) returned by call to the request_token API |
String |
Variable |
ShoppingCart |
Merchant Shopping Cart details. |
XML |
- |
|
OriginUrl |
Identifies the URL of the page that will initialize the lightbox. |
String |
Variable |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
|
ShoppingCart |
CurrencyCode |
Defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars. All MonetaryValues will be modified by the CurrencyCode |
Alpha |
3 |
Subtotal |
Total sum of all the items in the cart excluding shipping, handling and tax. Integer without the decimal e.g. $119.00 USD will be 11900. |
Integer |
1-12 |
|
ShoppingCartItem |
Details of a single shopping cart item. |
XML |
- |
|
ShoppingCartItem |
Description |
Describes a single shopping cart item. |
String |
1-100 |
Quantity |
Number of a single shopping cart item. |
Integer |
1-12 |
|
Value |
Price or monetary value of a single shopping cart item. Cost * Quantity. Integer without decimal e.g., $100.00 is 10000. |
Integer |
1-12 |
|
ImageURL |
Link to shopping cart item image. URLs must be HTTPS, and not HTTP. |
String |
0-2000 |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
|
ShoppingCartResponse |
Element |
Description |
Type |
Min- Max |
OAuthToken |
Request Token (oauth_token) returned by call to the request_token API |
String |
Variable |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
<?xml version="1.0" ?> <ShoppingCartRequest> <OAuthToken>f7f16d8462a9424365498afade20caaa</OAuthToken> <ShoppingCart> <CurrencyCode>USD</CurrencyCode> <Subtotal>11900</Subtotal> <ShoppingCartItem> <Description>This is one item</Description> <Quantity>1</Quantity> <Value>1900</Value> </ShoppingCartItem> <ShoppingCartItem> <Description>Five items</Description> <Quantity>5</Quantity> <Value>10000</Value> <ImageURL>https://somemerchant.com/someimage</ImageURL> </ShoppingCartItem> </ShoppingCart> <OriginUrl>https://somemerchant.com</OriginUrl> </ShoppingCartRequest>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ShoppingCartResponse> <OAuthToken>a747f7e7c2e0c3048843f640b92806c8</OAuthToken> </ShoppingCartResponse>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="ShoppingCartResponse" type="ShoppingCartResponse"/> <xs:complexType name="ShoppingCartResponse"> <xs:sequence> <xs:element name="OAuthToken" type="xs:string" /> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any" /> </xs:sequence> <xs:anyAttribute /> </xs:complexType> </xs:schema>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ShoppingCartResponse> <OAuthToken>93dcec2e58e1bee050301bb2ee7d9331</OAuthToken> </ShoppingCartResponse>
Redirect to MasterPass |
Callback from MasterPass |
|
---|---|---|
oauth_token |
X |
X |
oauth_verifier |
X |
|
checkout_resource_url |
X |
|
acceptable_cards |
X |
|
checkout_identifier |
X |
|
version |
X |
|
suppress_shipping_address |
X |
|
auth_basic |
X |
|
accept_reward_program |
X |
|
shipping_location_profile |
X |
Redirect to MasterPass |
Description |
Possible Values |
|
---|---|---|---|
Oauth Token |
oauth_token |
oauth_token is sent in the signature base string, authorization header and redirect URL |
Variable |
Redirect URL Parameters |
acceptable_cards |
Comma delimited list of accepted cards. |
master, amex, diners, discover, maestro, visa |
checkout_identifier |
Checkout identifier generated when creating a checkout project on MasterPass Merchant portal |
Variable |
|
version |
Attribute to indicate which Checkout XML version to return. |
v5 |
|
suppress_shipping_address |
Flag to suppress the shipping options presented to the user. This parameter is optional and will default to false. |
true false |
|
auth_level |
Flag to reduce the 3DS authentication from advanced to basic on per transaction basis. Note: the 3DS level must be set to advance on the merchant profile to be reduced to basic with this flag. Possible value = basic. This parameter is optional and only used when 3DS authentication is used. |
basic |
|
accept_reward_program |
Optional flag to specify if you want MasterPass to return consumer's reward program |
true / false |
|
shipping_location_profile |
ID of shipping location profile |
variable |
|
Callback from MasterPass |
Description |
Possible Values |
|
Oauth Token |
oauth_token |
oauth_token is sent in the signature base string, authorization header and redirect URL |
Variable |
Access Token |
oauth_verifier |
Verifier is returned on the callback and used in the access token request |
Variable |
checkout_resource_url |
Endpoint used to request the users billing and shipping information from MasterPass |
Variable |
https://sandbox.masterpass.com/Checkout/Authorize?oauth_token=c43d6591aa0d01ba85d95f8c1832983f&acceptable_cards=master,amex,diners,discover,maestro,visa&checkout_identifier=a4a6x1ywxlkxzhensyvad1hepuouaesuv&version=v6&suppress_shipping_address=false&accept_reward_program=false
http://www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc
Note: the checkout_resource_url field must be URL decoded.
access_token Request |
access_token Response |
|
---|---|---|
oauth_signature |
X |
|
oauth_version |
X |
|
oauth_nonce |
X |
|
oauth_signature_method |
X |
|
oauth_consumer_key |
X |
|
oauth_timestamp |
X |
|
realm |
X |
|
oauth_token |
X |
X |
oauth_expires_in |
X |
|
oauth_token_secret |
X |
|
xoauth_request_auth_url |
X |
|
oauth_verifier |
X |
Access Token-Request |
Description |
Possible Values |
|
---|---|---|---|
Signature Base String Authorization Header |
oauth_signature |
RSA/SHA1 signature generated from the signature base string |
Variable |
oauth_version |
Oauth version. |
1.0 |
|
oauth_nonce |
Unique alphanumeric string generated from code |
Variable |
|
oauth_signature_method |
oauth signature method |
RSA-SHA1 |
|
oauth_consumer_key |
Consumer Key generated when creating a checkout project on MasterPass Merchant portal |
Variable |
|
oauth_timestamp |
Current timestamp |
Variable |
|
realm |
Used to differentiate between our mobile and full site. Currently not used. |
eWallet |
|
oauth_verifier |
Verifier is returned on the callback and used in the access token request |
||
oauth_token |
oAuth token obtained from request token call |
Variable |
|
Access Token-Response |
Description |
Possible Values |
|
Oauth Token |
oauth_token |
oauth_token is sent in the signature base string, authorization header and redirect URL |
Variable |
Request Token |
oauth_expires_in |
Time the Request Token expires in seconds |
900 |
oauth_token_secret |
Oauth Secret |
Variable |
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer%2Fv1%2Faccess_token&oauth_callback%3Dhttp%253A%252F%252Fprojectabc.com%252Fmerchant%252FCallback.jsp%26oauth_consumer_key%3DZGho8Df8vqW-IpGCIu559HYriL093IBXdJeKavp4dce9db2a%25216464586653467358724b616c74475445443349466a413d3d%26oauth_nonce%3D1144858422275061%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1339613436%26oauth_token%3Da02c5c5c1a128c2cebc650ea9aa3dfb7%26oauth_verifier%3D96782690ce6289d0faf45be777d2d86f%26oauth_version%3D1.0
POST /oauth/consumer/v1/access_token HTTP/1.1Authorization: OAuth oauth_callback="http%3A%2F%2Fprojectabc.com%2Fmerchant%2FCallback.jsp",oauth_signature="OKcp2KmzUEr8kqs%2F7m2ePV6uJ30n786AnZ0kvJSNGV4Q8%2FP3%2Bs7lqv7YIk0yb2h0fUTC7gSHsfJwmCCk4ES%2FlWVIpSRmVxotgLacxj%2FXI08DS0BZ0XMZZIkhY5Dcg775U3Re4GRN4xa9vmbztOBd%2BKkNyFIw35To22N1ZUHrYpI%3D",oauth_version="1.0",oauth_nonce="1144858422275061",oauth_signature_method="RSA-SHA1",oauth_consumer_key="ZGho8Df8vqW-IpGCIu559HYriL093IBXdJeKavp4dce9db2a%216464586653467358724b616c74475445443349466a413d3d",oauth_token="a02c5c5c1a128c2cebc650ea9aa3dfb7",oauth_verifier="96782690ce6289d0faf45be777d2d86f",oauth_timestamp="1339613436",realm="eWallet"
oauth_token=9429f23bd08f992c41fb5ddabcc03ecd&oauth_token_secret=cd1ab178419c2111fb1171083f5dc8d9
Checkout resource Request |
Checkout Resource Response |
|
---|---|---|
oauth_signature |
X |
|
oauth_version |
X |
|
oauth_nonce |
X |
|
oauth_signature_method |
X |
|
oauth_consumer_key |
X |
|
oauth_timestamp |
X |
|
realm |
X |
|
oauth_token |
X |
|
checkout_resource_url |
Used as endpoint |
|
Checkout XML |
X |
Checkout Resource-Request |
Description |
Possible Values |
|
---|---|---|---|
Signature Base String Authorization Header |
oauth_signature |
RSA/SHA1 signature generated from the signature base string |
Variable |
oauth_version |
Oauth version. |
1.0 |
|
oauth_nonce |
Unique alphanumeric string generated from code |
Variable |
|
oauth_signature_method |
oauth signature method. |
RSA-SHA1 |
|
oauth_consumer_key |
Consumer Key generated when creating a checkout project on MasterPass Merchant portal |
Variable |
|
oauth_timestamp |
Current timestamp |
Variable |
|
realm |
Used to differentiate between our mobile and full site. Currently not used. |
eWallet |
|
oauth_verifier |
Verifier is returned on the callback and used in the access token request |
||
Checkout Resource-Response |
Description |
Possible Values |
|
Oauth Token |
oauth_token |
oauth_token is sent in the signature base string, authorization header and redirect URL |
Variable |
Access Token |
checkout_resource_url |
Endpoint used to request the users billing and shipping information from MasterPass |
Variable |
Transfer XML Strings |
Checkout XML |
GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F349484&oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3D25780242027605%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380053717 %26oauth_token%3Dc531cce64ca2d88ecb223a8a37afe98e%26oauth_version%3D1.0
GET /masterpass/v6/checkout/4400 HTTP/1.1 Authorization: OAuth oauth_signature="CKs9xjeHksuVNKotsRmoOG0Rwmveoc2dTqnNw8IwlsZeG1ZNkVrPsTjde32YBndHR7iLFvujrY1GJRFsWHFeQGVFbCidGUVbOwtDtm5ArJPTIbedw21GhhXGWRrRpjh4ZhHLDOdSxtxjSCJaHFQkfGyq%2B0DHhMLLYizIzbH8%2Fp0%3D",oauth_version="1.0",oauth_nonce="25780242027605",oauth_signature_method="RSA-SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_token="c531cce64ca2d88ecb223a8a37afe98e",oauth_timestamp="1380053717",realm="eWallet"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="Checkout" type="Checkout"/> <xs:complexType name="Checkout"> <xs:sequence> <xs:element name="Card" type="Card"/> <xs:element name="TransactionId" type="xs:string"/> <xs:element name="Contact" type="Contact"/> <xs:element name="ShippingAddress" type="ShippingAddress" minOccurs="0"/> <xs:element name="AuthenticationOptions" type="AuthenticationOptions" minOccurs="0"/> <xs:element name="RewardProgram" type="RewardProgram" minOccurs="0"/> <xs:element name="WalletID" type="xs:string"/> <xs:element name="PreCheckoutTransactionId" type="xs:string" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="AuthenticationOptions"> <xs:sequence> <xs:element name="AuthenticateMethod" type="xs:string" minOccurs="0"/> <xs:element name="CardEnrollmentMethod" type="xs:string" minOccurs="0"/> <xs:element name="CAvv" type="xs:string" minOccurs="0"/> <xs:element name="EciFlag" type="xs:string" minOccurs="0"/> <xs:element name="MasterCardAssignedID" type="xs:string" minOccurs="0"/> <xs:element name="PaResStatus" type="xs:string" minOccurs="0"/> <xs:element name="SCEnrollmentStatus" type="xs:string" minOccurs="0"/> <xs:element name="SignatureVerification" type="xs:string" minOccurs="0"/> <xs:element name="Xid" type="xs:string" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="Card"> <xs:sequence> <xs:element name="BrandId" type="NonEmptyString"/> <xs:element name="BrandName" type="NonEmptyString"/> <xs:element name="AccountNumber" type="NonEmptyString"/> <xs:element name="BillingAddress" type="Address"/> <xs:element name="CardHolderName" type="NonEmptyString"/> <xs:element name="ExpiryMonth" type="Month" minOccurs="0"/> <xs:element name="ExpiryYear" type="Year" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="Address"> <xs:sequence> <xs:element name="City" type="NonEmptyString"/> <xs:element name="Country" type="Country"/> <xs:element name="CountrySubdivision" type="NonEmptyString" minOccurs="0"/> <xs:element name="Line1" type="NonEmptyString"/> <xs:element name="Line2" type="NonEmptyString" minOccurs="0"/> <xs:element name="Line3" type="NonEmptyString" minOccurs="0"/> <xs:element name="PostalCode" type="NonEmptyString" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="Contact"> <xs:sequence> <xs:element name="FirstName" type="NonEmptyString"/> <xs:element name="MiddleName" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="150"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="LastName" type="NonEmptyString"/> <xs:element name="Gender" type="Gender" minOccurs="0"/> <xs:element name="DateOfBirth" type="DateOfBirth" minOccurs="0"/> <xs:element name="NationalID" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="150"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="Country" type="Country"/> <xs:element name="EmailAddress" type="EmailAddress"/> <xs:element name="PhoneNumber" type="xs:string"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="DateOfBirth"> <xs:sequence> <xs:element name="Year"> <xs:simpleType> <xs:restriction base="xs:int"> <xs:minInclusive value="1900"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="Month" type="Month"/> <xs:element name="Day"> <xs:simpleType> <xs:restriction base="xs:int"> <xs:minInclusive value="1"/> <xs:maxInclusive value="31"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:simpleType name="Gender"> <xs:restriction base="xs:token"> <xs:enumeration value="M"/> <xs:enumeration value="F"/> </xs:restriction> </xs:simpleType> <xs:complexType name="ShippingAddress"> <xs:complexContent> <xs:extension base="Address"> <xs:sequence> <xs:element name="RecipientName" type="NonEmptyString"/> <xs:element name="RecipientPhoneNumber" type="xs:string"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> <xs:complexType name="RewardProgram"> <xs:sequence> <xs:element name="RewardNumber" type="xs:string"/> <xs:element name="RewardId" type="xs:string"/> <xs:element name="RewardName" type="xs:string" minOccurs="0"/> <xs:element name="ExpiryMonth" type="Month" minOccurs="0"/> <xs:element name="ExpiryYear" type="Year" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:simpleType name="NonEmptyString"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:whiteSpace value="collapse"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="Country"> <xs:restriction base="xs:string"> <xs:pattern value="[A-Z]{2}"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="EmailAddress"> <xs:restriction base="xs:string"> <xs:pattern value="[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*@[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="Month"> <xs:restriction base="xs:int"> <xs:minInclusive value="1"/> <xs:maxInclusive value="12"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="Year"> <xs:restriction base="xs:int"> <xs:minInclusive value="2013"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpleType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/> </xs:sequence> <xs:anyAttribute/> </xs:complexType> </xs:schema>
URL: https://api.mastercard.com/online/v6/checkout/512345?wallet=phw
<Checkout> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <AccountNumber>5435579315709649</AccountNumber> <BillingAddress> <City>Anytown</City> <Country>US</Country> <Line1>100 Not A Real Street</Line1> <PostalCode>63011</PostalCode> </BillingAddress> <CardHolderName>Joe Test</CardHolderName> <ExpiryMonth>02</ExpiryMonth> <ExpiryYear>2016</ExpiryYear> </Card> <TransactionId>72525</TransactionId> <Contact> <FirstName>Joe</FirstName> <MiddleName>M</MiddleName> <LastName>Test</LastName> <Gender>M</Gender> <DateOfBirth> <Year>1975</Year> <Month>03</Month> <Day>28</Day> </DateOfBirth> <NationalID>30258374209</NationalID> <Country>US</Country> <EmailAddress>joe.test@email.com</EmailAddress> <PhoneNumber>1-9876543210</PhoneNumber> </Contact> <ShippingAddress> <City>O Fallon</City> <Country>US</Country> <CountrySubdivision>US-AK</CountrySubdivision> <Line1>1 main street</Line1> <PostalCode>63368</PostalCode> <RecipientName>Joe Test</RecipientName> <RecipientPhoneNumber>1-9876543210</RecipientPhoneNumber> </ShippingAddress> <WalletID>101</WalletID> <RewardProgram> <RewardNumber>123</RewardNumber> <RewardId>1234</RewardId> <RewardName>ABC Rewards</RewardName> <ExpiryMonth>02</ExpiryMonth> <ExpiryYear>2015</ExpiryYear> </RewardProgram> </Checkout>
CheckoutXML |
Element |
Description |
Type |
Min-Max |
---|---|---|---|---|
Checkout |
Root Element |
XML |
- |
|
Checkout |
Card |
Child Element |
XML |
- |
Card |
BrandId |
Identifies the card brand id e.g. master for MasterCard. |
Alpha Numeric |
0-8 |
BrandName |
Identifies the card brand name e.g. MasterCard |
String |
0-255 |
|
AccountNumber |
Card number or primary account number that identifies the card |
Integer |
13-24 |
|
BillingAddress |
Billing Address for the card holder. |
XML |
- |
|
CardHolderName |
Cardholder name |
String |
1-100 |
|
ExpiryMonth |
Expiration month displayed on the payment card. |
Date |
XML format |
|
ExpiryYear |
Expiration year displayed on the payment card. |
Date |
XML format |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
|
Checkout |
TransactionID |
Child Element |
String |
1-255 |
Checkout |
Contact |
Child Element |
XML |
|
Contact (V5 Updates) |
FirstName |
Contact First Name |
String |
1-20 |
Optional |
MiddleName |
Contact Middle Name or Initial |
String |
1-20 |
LastName |
Contact Surname |
String |
1-20 |
|
Optional* |
Gender |
Contact Gender (M or F) |
"M" or "F" |
|
Optional* |
DateOfBirth |
Contact DOB - YYYY/MM/DD |
Sequence: Year (Int); Month (Int) Day (Int) |
Y (4) M (2) D (2) |
Optional* (dependent on merchant country of incorporation and the consumer country of residence) |
NationalID |
Contact National Identification |
String |
1-150 |
Optional |
Country |
Contact Country of Residence |
String |
0-2 |
EmailAddress |
Contact Email Address |
String |
5-512 |
|
PhoneNumber |
Contact Phone |
String |
3-20 |
|
DateOfBirth |
Contact DOB |
|||
Year |
Contact DOB Year |
Integer |
4 |
|
Month |
Contact DOB Month |
Integer |
1-2 |
|
Day |
Contact DOB Day |
Integer |
1-2 |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
|
Checkout |
ShippingAddress |
Child Element |
XML |
- |
ShippingAddress |
Address |
Child Element |
XML |
- |
Address |
City |
Cardholder's city |
String |
0-25 |
Country |
Cardholder's country. Defined by ISO 3166-1 alpha-2 digit country codes e.g. US is United States, AU is Australia, CA is Canada, GB is United Kingdom, etc. |
String |
2 |
|
CountrySubdivision |
Cardholder's country subdivision. Defined by ISO 3166-1 alpha-2 digit code e.g. US-VA is Virginia, US-OH is Ohio |
String |
5 |
|
Line 1 |
Address line 1 used for Street number and Street Name. |
String |
1-40 |
|
Line 2 |
Address line 2 used for Apt Number, Suite Number ,etc. |
String |
0-40 |
|
Line 3 |
Address line 3 used to enter remaining address information if it does not fit in Line 1 and Line 2 |
String |
0-255 |
|
PostalCode |
Postal Code or Zip Code appended to mailing address for the purpose of sorting mail. |
String |
0-20 |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
|
ShippingAddress |
RecipientName |
Name of person set to receive the shipped order. |
String |
1-100 |
ShippingAddress |
RecipientPhoneNumber |
Phone of the person set to receive the shipped order. |
String |
3-20 |
Checkout |
AuthenticationOptions |
Child Element |
XML |
- |
AuthenticationOptions |
AuthenticateMethod |
Method used to authenticate the cardholder at checkout. Valid values are "MERCHANT ONLY", "3DS" and "No Authentication". |
Alpha |
NA |
CardEnrollmentMethod |
Method by which the card was added to the wallet. Valid values are: Manual Direct Provisioned 3DS Manual NFC Tap |
Alpha |
NA |
|
CAvv |
(CAVV) Cardholder Authentication Verification Value generated by card issuer upon successful authentication of the cardholder and which should be . This should be passed in the authorization message |
Alpha Numeric |
NA |
|
EciFlag: |
Electronic commerce indicator (ECI) flag. Present when the PaRes value is
"Y" or "A." Possible values are; |
Alpha Numeric |
NA |
|
MasterCardAssignedID |
This value is assigned by MasterCard and represents programs associated directly with Maestro cards. This field should be supplied in the authorization request by the merchant. |
Alpha Numeric |
NA |
|
PaResStatus |
A message formatted, digitally signed, and sent from the ACS (issuer) to the
MPI providing the results of the issuer's SecureCode/Verified by Visa
cardholder authentication. Possible values are: |
Alpha |
NA |
|
SCEnrollmentStatus |
SecureCode Enrollment Status: Indicates if the issuer of the card supports
payer authentication for this card. Possible values are; |
Alpha |
NA |
|
SignatureVerification: |
Signature Verification. Possible values are: |
Alpha |
NA |
|
XID |
Transaction identifier resulting from authentication processing. |
Alpha Numeric |
NA |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
||
Checkout |
Reward Program |
Child Element |
XML |
|
Reward Program |
RewardNumber |
Consumer's reward number associated with the reward program |
Alpha Numeric |
|
Reward Program |
RewardId |
ID associated with the reward program |
Alpha Numeric |
|
RewardName |
Name of reward program |
Alpha Numeric |
||
ExpiryMonth |
Month the reward program expires |
Alpha Numeric |
||
ExpiryYear |
Year the reward program expires |
Alpha Numeric |
||
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
|
PreCheckoutTransactionId |
Pre Checkout Transaction ID |
ID associated with the PreCheckout Transaction |
Alpha Numeric |
* Only when legally required and enabled by MasterPass
Checkout resource Request |
Checkout Resource Response |
|
---|---|---|
oauth_signature |
X |
|
oauth_version |
X |
|
oauth_nonce |
X |
|
oauth_signature_method |
X |
|
oauth_consumer_key |
X |
|
oauth_timestamp |
X |
|
realm |
X |
|
oauth_token |
X |
|
PreCheckout Data Request XML |
X |
|
PreCheckout Data Response XML |
X |
PreCheckout Resource-Request |
Description |
Possible Values |
|
---|---|---|---|
Signature Base String Authorization Header |
oauth_signature |
RSA/SHA1 signature generated from the signature base string |
Variable |
oauth_version |
Oauth version. |
1.0 |
|
oauth_nonce |
Unique alphanumeric string generated from code |
Variable |
|
oauth_signature_method |
oauth signature method. |
RSA-SHA1 |
|
oauth_consumer_key |
Consumer Key generated when creating a checkout project on MasterPass Merchant portal |
Variable |
|
oauth_timestamp |
Current timestamp |
Variable |
|
oauth_token |
Long access token used to retrieve precheckout data |
||
realm |
Used to differentiate between our mobile and full site. Currently not used. |
eWallet |
|
Transfer XML Strings |
PreCheckout Data Request XML |
Details of the PreCheckout Request |
|
PreCheckout Resource-Response |
Description |
Possible Values |
|
Transfer XML Strings |
Pre Checkout XML |
GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F349484&oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3D25780242027605%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380053717 %26oauth_token%3Dc531cce64ca2d88ecb223a8a37afe98e%26oauth_version%3D1.0
POST /masterpass/v6/precheckout/4400 HTTP/1.1Authorization: OAuth oauth_signature="CKs9xjeHksuVNKotsRmoOG0Rwmveoc2dTqnNw8IwlsZeG1ZNkVrPsTjde32YBndHR7iLFvujrY1GJRFsWHFeQGVFbCidGUVbOwtDtm5ArJPTIbedw21GhhXGWRrRpjh3ZhHLDOdSxtxjSCJaHFQkfGyq%2B0DHhMLLYizIzbH8%2Fp0%3D",oauth_version="1.0",oauth_nonce="25780242027605",oauth_signature_method="RSA-SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_token="c531cce64ca2d88ecb223a8a37afe98e",oauth_timestamp="1380053717",realm="eWallet"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="PrecheckoutDataRequest" type="PrecheckoutDataRequest"/> <xs:complexType name="PrecheckoutDataRequest"> <xs:sequence> <xs:element name="PairingDataTypes" type="PairingDataTypes"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="PairingDataType" type="PairingDataType"/> <xs:complexType name="PairingDataType"> <xs:sequence> <xs:element name="Type"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="CARD"/> <xs:enumeration value="ADDRESS"/> <xs:enumeration value="REWARD_PROGRAM"/> <xs:enumeration value="PROFILE"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="PairingDataTypes" type="PairingDataTypes"/> <xs:complexType name="PairingDataTypes"> <xs:sequence> <xs:element name="PairingDataType" type="PairingDataType" minOccurs="1" maxOccurs="unbounded"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/> </xs:sequence> <xs:anyAttribute/> </xs:complexType> </xs:schema>
<PrecheckoutDataRequest> <PairingDataTypes> <PairingDataType> <Type>CARD</Type> </PairingDataType> <PairingDataType> <Type>ADDRESS</Type> </PairingDataType> <PairingDataType> <Type>PROFILE</Type> </PairingDataType> <PairingDataType> <Type>REWARD_PROGRAM</Type> </PairingDataType> </PairingDataTypes> </PrecheckoutDataRequest>
PreCheckoutXML |
Element |
Description |
Type |
Min-Max |
---|---|---|---|---|
PrecheckoutDataRequest |
Root Element |
XML |
- |
|
PrecheckoutDataRequest |
PairingDataTypes |
Child Element |
XML |
- |
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
|
PairingDataType |
Child Element |
XML |
- |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
|
PairingDataType |
PairingDataType |
Child Element |
XML |
- |
PairingDataType |
PairingDataType |
Card, ShippingAddress, Reward_Program, Profile |
String |
- |
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="PrecheckoutDataResponse" type="PrecheckoutDataResponse"/> <xs:complexType name="PrecheckoutDataResponse"> <xs:sequence> <xs:element name="PrecheckoutData" type="PrecheckoutData"/> <xs:element name="WalletPartnerLogoUrl" type="xs:anyURI"/> <xs:element name="MasterpassLogoUrl" type="xs:anyURI"/> <xs:element name="LongAccessToken" type="xs:string" minOccurs="1"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="PrecheckoutData" type="PrecheckoutData"/> <xs:complexType name="PrecheckoutData"> <xs:sequence> <xs:element name="Cards" type="PrecheckoutCards"/> <xs:element name="Contact" type="Contact" minOccurs="0"/> <xs:element name="ShippingAddresses" type="PrecheckoutShippingAddresses"/> <xs:element name="RewardPrograms" type="PrecheckoutRewardPrograms"/> <xs:element name="WalletName" type="xs:string" minOccurs="1"/> <xs:element name="PrecheckoutTransactionId" type="xs:string" /> <xs:element name="ConsumerWalletId" type="xs:string" minOccurs="1"/> <xs:element name="Errors" type="Errors" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="PrecheckoutCards" type="PrecheckoutCards"/> <xs:complexType name="PrecheckoutCards"> <xs:sequence> <xs:element name="Card" type="PrecheckoutCard" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="PrecheckoutCard" type="PrecheckoutCard"/> <xs:complexType name="PrecheckoutCard"> <xs:sequence> <xs:element name="BrandId" type="xs:string" /> <xs:element name="BrandName" type="xs:string" /> <xs:element name="BillingAddress" type="Address" /> <xs:element name="CardHolderName" type="xs:string" /> <xs:element name="ExpiryMonth" type="Month" minOccurs="0"/> <xs:element name="ExpiryYear" type="Year" minOccurs="0"/> <xs:element name="CardId" type="xs:string"></xs:element> <xs:element name="LastFour" type="xs:string" /> <xs:element name="CardAlias" type="xs:string" /> <xs:element name="SelectedAsDefault" type="xs:boolean" /> <xs:element name="BNBUnverified" type="xs:boolean" /> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="Contact"> <xs:sequence> <xs:element name="FirstName" type="NonEmptyString"/> <xs:element name="MiddleName" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="150"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="LastName" type="NonEmptyString"/> <xs:element name="Gender" type="Gender" minOccurs="0"/> <xs:element name="DateOfBirth" type="DateOfBirth" minOccurs="0"/> <xs:element name="NationalID" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="150"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="Country" type="Country"/> <xs:element name="EmailAddress" type="EmailAddress"/> <xs:element name="PhoneNumber" type="xs:string"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:simpleType name="NonEmptyString"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:whiteSpace value="collapse"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="Gender"> <xs:restriction base="xs:token"> <xs:enumeration value="M"/> <xs:enumeration value="F"/> </xs:restriction> </xs:simpleType> <xs:complexType name="DateOfBirth"> <xs:sequence> <xs:element name="Year"> <xs:simpleType> <xs:restriction base="xs:int"> <xs:minInclusive value="1900"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="Month" type="Month"/> <xs:element name="Day"> <xs:simpleType> <xs:restriction base="xs:int"> <xs:minInclusive value="1"/> <xs:maxInclusive value="31"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:simpleType name="Month"> <xs:restriction base="xs:int"> <xs:minInclusive value="1"/> <xs:maxInclusive value="12"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="Year"> <xs:restriction base="xs:int"> <xs:minInclusive value="2013"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="Country"> <xs:restriction base="xs:string"> <xs:pattern value="[A-Z]{2}"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="EmailAddress"> <xs:restriction base="xs:string"> <xs:pattern value="[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*@[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*"/> </xs:restriction> </xs:simpleType> <xs:element name="PrecheckoutShippingAddresses" type="PrecheckoutShippingAddresses"/> <xs:complexType name="PrecheckoutShippingAddresses"> <xs:sequence> <xs:element name="ShippingAddress" type="PrecheckoutShippingAddress" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="PrecheckoutShippingAddress" type="PrecheckoutShippingAddress"/> <xs:complexType name="PrecheckoutShippingAddress"> <xs:complexContent> <xs:extension base="Address"> <xs:sequence> <xs:element name="RecipientName" type="xs:string" /> <xs:element name="RecipientPhoneNumber" type="xs:string" /> <xs:element name="AddressId" type="xs:string"/> <xs:element name="SelectedAsDefault" type="xs:boolean" /> <xs:element name="ShippingAlias" type="xs:string" /> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> <xs:complexType name="Address"> <xs:sequence> <xs:element name="City" type="NonEmptyString"/> <xs:element name="Country" type="Country"/> <xs:element name="CountrySubdivision" type="NonEmptyString" minOccurs="0"/> <xs:element name="Line1" type="NonEmptyString"/> <xs:element name="Line2" type="NonEmptyString" minOccurs="0"/> <xs:element name="Line3" type="NonEmptyString" minOccurs="0"/> <xs:element name="PostalCode" type="NonEmptyString" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="PrecheckoutRewardPrograms" type="PrecheckoutRewardPrograms"/> <xs:complexType name="PrecheckoutRewardPrograms"> <xs:sequence> <xs:element name="RewardProgram" type="PrecheckoutRewardProgram" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="PrecheckoutRewardProgram" type="PrecheckoutRewardProgram"/> <xs:complexType name="PrecheckoutRewardProgram"> <xs:sequence> <xs:element name="RewardNumber" type="xs:string"/> <xs:element name="RewardId" type="xs:string"/> <xs:element name="RewardName" type="xs:string" minOccurs="0"/> <xs:element name="ExpiryMonth" type="Month" minOccurs="0"/> <xs:element name="ExpiryYear" type="Year" minOccurs="0"/> <xs:element name="RewardProgramId" type="xs:string"/> <xs:element name="RewardLogoUrl" type="xs:string" /> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="Error"> <xs:sequence> <xs:element name="Description" type="xs:string" minOccurs="0"/> <xs:element name="ReasonCode" type="xs:string"/> <xs:element name="Recoverable" type="xs:boolean"/> <xs:element name="Source" type="xs:string"/> <xs:element name="Details" type="Details" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> <xs:complexType name="Errors"> <xs:sequence> <xs:element name="Error" type="Error" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="Details"> <xs:sequence> <xs:element name="Detail" type="Detail" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="Detail"> <xs:sequence> <xs:element name="Name" type="xs:string"/> <xs:element name="Value" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/> </xs:sequence> <xs:anyAttribute/> </xs:complexType> </xs:schema>
<PrecheckoutDataResponse> <PrecheckoutData> <Cards> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <CardHolderName>Joe Cardholder</CardHolderName> <ExpiryMonth>2</ExpiryMonth> <ExpiryYear>2016</ExpiryYear> <CardId>10153047</CardId> <LastFour>2149</LastFour> <CardAlias>Rewards Card</CardAlias> <SelectedAsDefault>false</SelectedAsDefault> </Card> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <CardHolderName>Joe Cardholder</CardHolderName> <ExpiryMonth>2</ExpiryMonth> <ExpiryYear>2016</ExpiryYear> <CardId>12963120</CardId> <LastFour>0144</LastFour> <SelectedAsDefault>true</SelectedAsDefault> </Card> </Cards> <Contact> <FirstName>Joe</FirstName> <LastName>Cardholder</LastName> <Country>US</Country> <EmailAddress>joe.cardholder@gmail.com</EmailAddress> <PhoneNumber>1-6365555309</PhoneNumber> </Contact> <ShippingAddresses> <ShippingAddress> <City>chesterfield</City> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>123 main st</Line1> <Line2/> <Line3/> <PostalCode>63017</PostalCode> <RecipientName>Joe Cardholder</RecipientName> <RecipientPhoneNumber>1-6365555309</RecipientPhoneNumber> <AddressId>10423457</AddressId> <SelectedAsDefault>true</SelectedAsDefault> </ShippingAddress> <ShippingAddress> <City>St Louis</City> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>11642 Frontier Dr</Line1> <Line2/> <Line3/> <PostalCode>63146</PostalCode> <RecipientName>Joe Cardholder</RecipientName> <RecipientPhoneNumber>1-6365555309</RecipientPhoneNumber> <AddressId>10073359</AddressId> <SelectedAsDefault>false</SelectedAsDefault> </ShippingAddress> </ShippingAddresses> <WalletName>Mobile</WalletName> <PrecheckoutTransactionId>a4d6x6s-55pqrj-hyko44a5-1-hyq76c51-a4a</PrecheckoutTransactionId> <ConsumerWalletId>10073003</ConsumerWalletId> </PrecheckoutData> <WalletPartnerLogoUrl>https://www.masterpass.com/walletlogo.png </WalletPartnerLogoUrl> <MasterpassLogoUrl>https://www.masterpass.com/masterpasslogo.png </MasterpassLogoUrl> <LongAccessToken>a2abae6b0b21be8fc23113bf8477a7dd1f0f4041</LongAccessToken> </PrecheckoutDataResponse>
PreCheckouthataXML |
Element |
Description |
Type |
Min-Max |
---|---|---|---|---|
PrecheckoutData |
Root Element |
XML |
- |
|
PrecheckoutData |
Cards |
Child Element |
PrecheckoutCard |
- |
Contact |
Child Element |
Contact |
- |
|
ShippingAddresses |
Child Element |
PrecheckoutShippingAddress |
- |
|
WalletName |
Child Element |
String |
- |
|
RewardPrograms |
Child Element |
PrecheckoutRewardProgram |
- |
|
PrecheckoutTransactionId |
Child Element |
String |
- |
|
ConsumerWalletId |
Child Element |
String |
- |
|
WalletPartnerLogoUrl |
Child Element |
String |
- |
|
MasterpassLogoUrl |
Child Element |
String |
||
LongAccessToken |
Child Element |
String |
||
Errors |
Child Element |
String |
- |
|
PrecheckoutCard |
Root Element |
String |
- |
|
CardId |
Child Element |
String |
- |
|
BrandId |
Child Element |
String |
- |
|
BrandName |
Child Element |
String |
- |
|
BillingAddress |
Child Element |
Address |
- |
|
CardHolderName |
Child Element |
String |
- |
|
LastFour |
Child Element |
String |
- |
|
CardAlias |
Child Element |
String |
- |
|
ExpiryMonth |
Child Element |
String |
0-9, 2 |
|
ExpiryYear |
Child Element |
String |
0-9, 4 |
|
SelectedAsDefault |
Child Element |
Boolean |
- |
|
ExtensionPoint |
Any |
- |
||
Contact |
Root Element |
String |
- |
|
Contact |
FirstName |
Child Element |
String |
- |
MiddleName |
Child Element |
String |
1-150 |
|
LastName |
Child Element |
String |
- |
|
Gender* |
Child Element |
String |
M/F |
|
DateOfBirth |
Child Element |
String |
- |
|
DateOfBirth |
Year |
Child Element |
Integer |
1900, 4 |
Month |
Child Element |
Integer |
1-12 |
|
Day |
Child Element |
Integer |
1-31 |
|
ExtensionPoint |
Any |
- |
||
Contact |
NationalId* |
Child Element |
String |
1-150 |
Country |
Child Element |
Country |
- |
|
EmailAddress |
Child Element |
EmailAddress |
- |
|
PhoneNumber |
Child Element |
String |
- |
|
ExtensionPoint |
Any |
- |
||
PrecheckoutShippingAddress |
Root Element |
String |
- |
|
PrecheckoutShippingAddress |
Address |
Child Element |
String |
- |
Address |
AddressId |
Child Element |
String |
- |
RecipientName |
Child Element |
String |
- |
|
RecipientPhoneNumber |
Child Element |
String |
- |
|
SelectedAsDefault |
Child Element |
Boolean |
- |
|
ShippingAlias |
Child Element |
String |
- |
|
ExtensionPoint |
Any |
- |
||
PrecheckoutRewardProgram |
Root Element |
String |
- |
|
PrecheckoutRewardProgram |
RewardProgramId |
Child Element |
String |
- |
RewardNumber |
Child Element |
String |
- |
|
RewardId |
Child Element |
String |
- |
|
RewardName |
Child Element |
String |
- |
|
ExpiryMonth |
Child Element |
String |
0-9, 2 |
|
ExpiryYear |
Child Element |
String |
0-9, 4 |
|
RewardLogo |
Child Element |
Logo |
- |
|
ExtensionPoint |
Any |
- |
||
Address |
Root Element |
String |
- |
|
Address |
Line1 |
Child Element |
String |
1-40 |
Line2 |
Child Element |
String |
0-40 |
|
Line3 |
Child Element |
String |
0-255 |
|
City |
Child Element |
String |
1-25 |
|
CountrySubdivision |
Child Element |
String |
0-255 |
|
PostalCode |
Child Element |
String |
0-10 |
|
Country |
Child Element |
String |
0-255 |
|
ExtensionPoint |
Any |
- |
||
Country |
Root Element |
String |
- |
|
Country |
Code |
Child Element |
String |
A-Z, 3 |
Name |
Child Element |
String |
- |
|
CallingCode |
Child Element |
String |
- |
|
Locale |
Child Element |
String |
- |
|
EmailAddress |
Root Element |
String |
- |
|
Logo |
Root Element |
String |
- |
|
Logo |
Ref |
Child Element |
String |
- |
Height |
Child Element |
String |
- |
|
Width |
Child Element |
String |
- |
|
BackgroundColor |
Child Element |
String |
- |
|
Url |
Child Element |
String |
- |
|
LongDescription |
Child Element |
String |
- |
|
Errors |
Root Element |
Error |
- |
|
Errors |
Error |
Child Element |
String |
- |
Error |
Description |
Child Element |
String |
- |
ReasonCode |
Child Element |
String |
- |
|
Recoverable |
Child Element |
Boolean |
- |
|
Source |
Child Element |
String |
- |
*Only when legally required and enabled by MasterPass
Starting with API v6, all schema container elements contain a new optional element named "ExtensionPoint". These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of "xs:any", meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an ExtensionPoint element, beyond any that may be defined by MasterPass in the future with a separate schema. Any such extensions will be optional. Further, only authorized schemas will be allowed inside ExtensionPoint elements, and any unknown elements will be dropped by MasterPass.
<ExtensionPoint> <s:SampleExtension xmlns:s=”https://www.masterpass.com/location/of/example/ns”> <s:SampleField>Sample Value</s:SampleField> </s:SampleExtension> <f:AnotherExampleExtension xmlns:f=”https://www.masterpass.com/location/of/example2/ns> Lightbox <f:SampleContainer> <f:AnotherSampleField>Sample Value</f:AnotherSampleField> </f:SampleContainer> </f:AnotherExampleExtension> </ExtensionPoint>
Post Transaction Request |
Post Transaction Response |
|
---|---|---|
oauth_signature |
X |
|
oauth_version |
X |
|
oauth_nonce |
X |
|
oauth_signature_method |
X |
|
oauth_consumer_key |
X |
|
oauth_timestamp |
X |
|
oauth_body_hash |
X |
|
MerchantTransactions XML |
X |
X |
Post Transaction-Request |
Description |
Possible Values |
|
---|---|---|---|
Signature Base String Authorization Header |
oauth_signature |
RSA/SHA1 signature generated from the signature base string |
Variable |
oauth_version |
Oauth version. |
1.0 |
|
oauth_nonce |
Unique alphanumeric string generated from code |
Variable |
|
oauth_signature_method |
oauth signature method. |
RSA-SHA1 |
|
oauth_consumer_key |
Consumer Key generated when creating a checkout project on MasterPass Merchant portal |
Variable |
|
oauth_timestamp |
Current timestamp |
Variable |
|
oauth_body_hash |
SHA1 hash of the message body |
Variable |
|
Transfer XML Strings |
Merchant Transactions XML |
Transaction details |
|
Post Transaction-Response |
Description |
Possible Values |
|
Transfer XML Strings |
Merchant Transactions XML |
Transaction details |
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Ftransaction &oauth_body_hash%3DycNt7A676VEY7i0SkyymKorihCg%253D%26oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3D26123188000346%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380054060%26oauth_version%3D1.0
POST /masterpass/v6/transaction HTTP/1.1Authorization: OAuth oauth_signature="Aom0wFGFI7ItYV1IZFn125BoD6jgFtdX15dQ8XbjvMGgKgKtJ5awV7wSMGwUcceGlpl52HFS%2B%2BOQzVrCdXUidvgeKOX1nHDFhns0l1yIaqGdkJQYR%2BCQGu1qo7xVjvzTqpXUlrc2uzVCjyLoQEroIWv5cAOj5l4aBxDopz7OKQA%3D",oauth_body_hash="ycNt7A676VEY7i0SkyymKorihCg%3D",oauth_version="1.0",oauth_nonce="26123188000346",oauth_signature_method="RSA-SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_timestamp="1380054060"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="MerchantTransactions" type="MerchantTransactions"/> <xs:complexType name="MerchantTransactions"> <xs:sequence> <xs:element name="MerchantTransactions" type="MerchantTransaction" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="MerchantTransaction"> <xs:sequence> <xs:element name="TransactionId" type="xs:string"/> <xs:element name="ConsumerKey" type="xs:string" minOccurs="0"/> <xs:element name="Currency" type="xs:string"/> <xs:element name="OrderAmount" type="xs:long"/> <xs:element name="PurchaseDate" type="xs:dateTime"/> <xs:element name="TransactionStatus" type="TransactionStatus"/> <xs:element name="ApprovalCode" type="xs:string"/> <xs:element name="PreCheckoutTransactionId" type="xs:string" minOccurs="0"/> <xs:element name="ExpressCheckoutIndicator" type="xs:boolean" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:simpleType name="TransactionStatus"> <xs:restriction base="xs:string"> <xs:enumeration value="Success"/> <xs:enumeration value="Failure"/> </xs:restriction> </xs:simpleType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/> </xs:sequence> <xs:anyAttribute/> </xs:complexType> </xs:schema>
<MerchantTransaction> <TransactionId>4549794</TransactionId> <ConsumerKey>0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d</ConsumerKey> <Currency>USD</Currency> <OrderAmount>1229</OrderAmount> <PurchaseDate>2014-08-01T14:52:57.539-05:00</PurchaseDate> <TransactionStatus>Success</TransactionStatus> <ApprovalCode>sample</ApprovalCode> <PreCheckoutTransactionId>a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947</PreCheckoutTransactionId> <ExpressCheckoutIndicator>false</ExpressCheckoutIndicator> </MerchantTransaction>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="MerchantTransactions" type="MerchantTransactions"/> <xs:complexType name="MerchantTransactions"> <xs:sequence> <xs:element name="MerchantTransactions" type="MerchantTransaction" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="MerchantTransaction"> <xs:sequence> <xs:element name="TransactionId" type="xs:string"/> <xs:element name="ConsumerKey" type="xs:string" minOccurs="0"/> <xs:element name="Currency" type="xs:string"/> <xs:element name="OrderAmount" type="xs:long"/> <xs:element name="PurchaseDate" type="xs:dateTime"/> <xs:element name="TransactionStatus" type="TransactionStatus"/> <xs:element name="ApprovalCode" type="xs:string"/> <xs:element name="PreCheckoutTransactionId" type="xs:string" minOccurs="0"/> <xs:element name="ExpressCheckoutIndicator" type="xs:boolean" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:simpleType name="TransactionStatus"> <xs:restriction base="xs:string"> <xs:enumeration value="Success"/> <xs:enumeration value="Failure"/> </xs:restriction> </xs:simpleType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/> </xs:sequence> <xs:anyAttribute/> </xs:complexType> </xs:schema>
<MerchantTransaction> <TransactionId>4549794</TransactionId> <ConsumerKey>0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d</ConsumerKey> <Currency>USD</Currency> <OrderAmount>1229</OrderAmount> <PurchaseDate>2014-08-01T14:52:57.539-05:00</PurchaseDate> <TransactionStatus>Success</TransactionStatus> <ApprovalCode>sample</ApprovalCode> <PreCheckoutTransactionId>a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947</PreCheckoutTransactionId> <ExpressCheckoutIndicator>false</ExpressCheckoutIndicator> </MerchantTransaction>
MerchantTransactionsRequest |
Element |
Description |
Type |
Min - Max |
---|---|---|---|---|
MerchantTransactions |
||||
MerchantTransaction |
MerchantTransaction |
XML |
- |
|
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
|
TransactionID |
Uses the TransactionID element of the Checkout XML |
String |
1-255 |
|
ConsumerKey |
Automatically generated when creating a checkout project on MasterPass Merchant portal. |
String |
97 |
|
Currency |
Currency of the transaction. Defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars. |
String |
3 |
|
OrderAmount |
(Integer) Transaction order amount without decimal e.g. 1500. |
Integer |
1-12 |
|
PurchaseDate |
Date and Time of the shopping cart purchase. |
Date |
XML format |
|
TransactionStatus |
State of the transaction. Indicates whether successful. Valid values are Success or Failure. |
String |
7 |
|
ApprovalCode |
Approval code returned by payment API. |
String |
6 |
|
PreCheckoutTransactionId |
Value returned from the PrecheckoutData call. |
String |
||
ExpressCheckoutIndicator |
True or False. Set to false for connected checkout |
Boolean |
||
ExtensionPoint |
Reserved for future enhancement. Optional |
Any |
- |
Starting with API v6, all schema container elements contain a new optional element named "ExtensionPoint". These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of "xs:any", meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an ExtensionPoint element, beyond any that may be defined by MasterPass in the future with a separate schema. Any such extensions will be optional. Further, only authorized schemas will be allowed inside ExtensionPoint elements, and any unknown elements will be dropped by MasterPass.
<ExtensionPoint> <s:SampleExtension xmlns:s=”https://www.masterpass.com/location/of/example/ns”> <s:SampleField>Sample Value</s:SampleField> </s:SampleExtension> <f:AnotherExampleExtension xmlns:f=”https://www.masterpass.com/location/of/example2/ns> <f:SampleContainer> <f:AnotherSampleField>Sample Value</f:AnotherSampleField> </f:SampleContainer> </f:AnotherExampleExtension> </ExtensionPoint>
Login to MasterCard's Developer Zone (https://developer.mastercard.com), click My Account, then My Dashboard.
On the My Dashboard page, click My Keys button, select the key you want to renew and then click on Renew Key button.
In order to renew the API Key, you need to supply a PEM encoded Certificate Request File. Choose the file, and click Submit. Notice the updated Key ID expiry date.
Note: If the CSR file is different than the CSR that was originally submitted when you created the key, make sure that your application is using the correct key store (.p12), otherwise calls to MasterPass services will fail.
From the Add a Key screen, Click Here, to launch the Key Tool utility.
Click on "Generate Keys and CSR" and then click on "Save to Files". Next screen will prompt you to select the password.
Choose the folder where you want to save the files. This utility will create the PEM and p12 file.
When enrolling for MasterPass,™ a merchant selects either Basic Checkout services, or Advanced Checkout payer authentication services. Basic Checkout is already offered with the core MasterPass™ offering, and facilitates a simple checkout experience. Advanced Checkout provides merchants a payer authentication service to enable a merchant to authenticate its transactions with the issuer of the applicable card account leveraging the 3D Secure protocol provided through the MasterCard® SecureCode or Verified by Visa programs (collectively, the "Programs").
Merchants have two authentication options to choose from when implementing "Buy with MasterPass" Button:
Basic Checkout: A simple checkout experience where a consumer logs in to their MasterPass™ wallet and selects their payment method for use at the merchant site. The payment method will be returned to the merchant for checkout completion.
Advanced Checkout: When this option is selected by a merchant, Advanced Checkout will, on behalf of a merchant, attempt authentication leveraging the MasterCard® SecureCode™ or Verified by Visa protocols, depending on the card selected by the consumer in connection with the purchase. At this time, MasterPass™ supports only the brands included here. A merchant may choose this service for each supported card brand offered, such as MasterCard cards, or Visa cards, or for both.
Before 'Advanced Checkout' is selected, a merchant must take the following actions:
The MasterCard® SecureCode™ and Verified by Visa payer authentication programs (also, "Programs") are based on the 3-D Secure Protocol.
Service Process Flow for Merchant who Select Advanced Checkout
MasterCard does not represent or warrant that the Advanced Checkout service referenced herein is free from defects and mistakes and provides the service on an "as is" basis. No particular results are promised or assured. Merchant expressly assumes all risk for the use of the Advanced Checkout service. MasterCard, at all times, and in its sole discretion, reserves the right to begin and stop supporting any particular brand, service and/or type of payment transaction.
Merchant indemnifies and holds harmless MasterCard from and against any claim, demand, loss, cost, or expense arising from or relating to use of the Advanced Checkout services. MasterCard expressly disclaims any responsibility with regard to the acts or omissions of any Merchant or other person in regard to its compliance with applicable law or regulation. The signing or electronic signature of the MasterPass™ Merchant Terms of Use for MasterPass™ services inclusive of Advanced Checkout, and the submission of any other forms related thereto, including the Information Sheet referenced above, indicates that the Merchant understands and agrees to the terms and conditions set forth herein. Merchant acknowledges that its acceptance of these terms and conditions is relied upon by MasterCard in permitting the Merchant's participation in MasterPass™ and Advanced Checkout.
© 2014 MasterCard. Proprietary and Confidential. All rights reserved.