Common Errors... 128 Support... 128
Common Errors
The following are the procedures to troubleshoot the most common errors that you may encounter.
If you get Error 400 when calling MasterPass web services: • Verify Authorization header is not missing from the request. • Verify Authorization header has the following:
– Signature
– Consumer Key (exists and correct length) – Nonce
– Signature Method – Timestamp
– Callback URL (Request Token call only) – oauth_verifier (Access Token call only) – oauth_token (Access Token call only)
If you get Error 401 when calling MasterPass web services:
• Verify that you are passing the Access Token in the get CheckoutXML call. If you get Error 403 - Forbidden when calling MasterPass services:
• Verify correct credentials or correct environment (that is, sandbox credentials with the prod URL).
• Verify timestamp.
If you get Error 500 when calling MasterPass web services:
• Verify oauth_body_hash exists and is correct (Post Transaction call only). • Verify Content-Type HTTP header is being sent.
• Verify correct private key.
• Verify signature is readable (for example, encoded incorrectly).
Support
This topic provides information on how to get additional support.
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 merchant testing, contact the implementation manager assigned to work with you on this implementation. If you don’t have an assigned implementation manager, send an email—with the following information (as applicable)—to [email protected]:
• Email Address • Country/Region
• Onboarding Model (Direct Merchant, Service Provider Merchant-by-Merchant or Service Provider File and API Onboarding)
• Environment of Integration (Sandbox or Production) • Checkout Version and Checkout Identifier
• Consumer Key
• Postback Details (Amount, Date and Time of recent Checkout)
• Detailed description of the issue, including expected and actual test results (if applicable) • Error Message(s)
• Screenshot(s) • Exact Timestamp
Appendix A Appendix
Appendix
This appendix provides additional information related to MasterPass™ integration process.
Lightbox Parameters... 131 OAuth Samples...134 Request Token...134 Merchant Initialization Service... 136 Shopping Cart Service... 141 Access Token Service... 147 Checkout Resource... 149 Pre-Checkout Resource...163 Postback Service...176 Renew Your Developer Zone Key...182 Developer Zone Key Tool Utility... 186 3-D Secure Overview...188 3-D Secure Service Description... 188 General Overview of MasterCard SecureCode and Verified by Visa Transaction
Authentication... 189 Important Merchant Information... 191
Lightbox Parameters
This section provides descriptions of the MasterPass™ Lightbox parameters.
Lightbox parameters invoked on clicking the Buy with MasterPass or Connect with MasterPass button
O = Optional; R = Required; A = Automatically populated
Parameter name
Data type
Card
Security Checkout 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 JCB: jcb
callbackUrl string 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. cancelCallback functio
n
O O This defines the function to be called when the flow is
cancelled by the consumer prior to completing checkout.
cardId string O Required for connected
checkout. Set to a valid payment card ID.
Parameter name
Data type
Card
Security Checkout Description
consumerWalletId string Required for connected
checkout to uniquely identify consumer.
failureCallback functio n
O O This defines the function to be called when the flow ends in failure.
Refer SDK for more examples. loyaltyEnabled boolean O This parameter defines if the
merchant is requesting
consumer’s loyalty details from MasterPass for the transaction. Valid values are True or False.
loyaltyId string O Optional for connected
checkout. Set to a valid loyalty card ID.
merchantCheckoutId string R R This is the checkout identifier which is used to identify the merchant and their checkout branding.
pairingRequestToken string O This is an OAuth token. 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 boolean O Set to "true" to disable step-up
authentication (advanced checkout) during any checkout flow. The default is "false".
Parameter name
Data type
Card
Security Checkout Description
requestedDataTypes string[] O 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.
This parameter is required when requestPairing is "true". requestPairing boolean O This indicates that the user is
being asked to enable pairing. It is automatically set to "true" for the "Connected" flow. The default for other flows is "false".
requestToken string R R This is an OAuth token.
shippingId string O Optional for connected
checkout. Set to a valid shipping destination ID.
shippingLocationProfile comma separat ed string
O This parameter defines Merchant’s Shipping Profile(s) for the transaction that they set in their account. Multiple values may be passed via comma separation (as in, no spaces within a profile name). For example,
"CHEERIO,AUONLY,NAmerica". successCallback functio
n
O O This defines the function to be called when the flow ends in success.
Parameter name
Data type
Card
Security Checkout Description
suppressShippingAddressEnable boolean O When set to “true,” the consumer placing the order through MasterPass Wallet will not provide a shipping address (for example, when the consumer purchases digital goods). When set to “false,” the consumer placing the order through MasterPass Wallet must provide a shipping address.
walletName string Required for connected
checkout to uniquely identify wallet name.
OAuth Samples
This topic provides information on OAuth samples.
Request Token
This section describes the Request Token parameters.
Request Token Parameters
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 Samples
request_token Request request_token Response
oauth_expires_in X
oauth_token_secret X
xoauth_request_auth_url X
Request Parameter Details
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_m
ethod
oAuth signature method. RSA-SHA1 oauth_consumer_ke
y
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_con firmed
Variable
Request Token—Response Description Possible Values
oauth_expires_in Time the Request Token expires in seconds
Variable oauth_token_secret Oauth Secret Variable xoauth_request_aut
h_url
Authorize URL Variable
Signature Base String Example
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer%2Fv1%2Freque st_token&oauth_callback%3Dhttp%253A%252F%252Fprojectabc.com%252Fmerchant%252F Callback.jsp%26oauth_consumer_key%3DZGho8Df8vqW- IpGCIu559HYriL093IBXdJeKavp4dce9db2a%25216464586653467358724b616c744754454433 49466a413d3d%26oauth_nonce%3D1143452272881219%26oauth_signature_method%3DRSA- SHA1%26oauth_timestamp%3D1339612030%26oauth_version%3D1.0 HTTP Request Example POST /oauth/consumer/v1/request_token HTTP/1.1 Authorization: OAuth oauth_callback="http%3A%2F%2Fprojectabc.com%2Fmerchant%2FCallback.jsp",oauth_ signature="pzNogGtgShe16%2FwhP4CsTRXkgJ1mv%2FKm6do5ZVi6doKzAJZ0m8QqhiERi5lRup hdyUkhW8LKdUL1TetPdxm32Vtr%2BQGF6n6IBjr8dGcyYmfaLyAYVhF%2Fx5oQhUDVpdXIc10dJ0m iUwZPbJ1QopN3ibeOzvgNxhEiHYKVnpvYEhc%3D",oauth_version="1.0",oauth_nonce="114 3452272881219",oauth_signature_method="RSA- SHA1",oauth_consumer_key="ZGho8Df8vqW- IpGCIu559HYriL093IBXdJeKavp4dce9db2a%216464586653467358724b616c74475445443349 466a413d3d",oauth_timestamp="1339612030",realm="eWallet" HTTP Response Example oauth_callback_confirmed=true&oauth_expires_in=900&oauth_token=a02c5c5c1a128c2 cebc650ea9aa3dfb7&oauth_token_secret=c2daaf0888779d82bd63524159bee91f&xoauth_r equest_auth_url=https%3A%2F%2Fsandbox.masterpass.com%2Fonline%2FCheckout%2FAut horize
Merchant Initialization Service
This section describes the Merchant Initialization parameters.
Merchant Initialization Parameters
Merchant Initialization resource Request Merchant Initialization Resource Response oauth_signature X oauth_version X oauth_nonce X OAuth Samples
Merchant Initialization resource Request Merchant Initialization Resource Response oauth_signature_method X oauth_consumer_key X oauth_timestamp X realm X oauth_body_hash X oauth_token X Merchant Initialization Request XML X Merchant Initialization Response XML X
Merchant Initialization Request Parameter Details
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_m
ethod
oauth signature method. RSA-SHA1 oauth_consumer_ke
y
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
Request XML
MerchantInitializatio nRequest XML
Merchant Initialization details
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
Signature Base String Example
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%merchantinitial ization&oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_key %3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a3 27474695545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4- B4263CB5A305%26oauth_signature_method%3DRSA- SHA1%26oauth_timestamp%3D1380049711%26oauth_version%3D1.0 HTTP Request Example POST /masterpass/v6/merchant-initialization HTTP/1.1 Authorization: OAuth realm="eWallet",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b 0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_signature_metho d="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%2FYvuJ2BtO4C 8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zrav b02oqTrVQH3Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D" XML
V6/merchant-initialization—XML Schema Request
<?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:element name="MerchantInitializationExtension" type="MerchantInitializationExtension"/> <xs:complexType name="MerchantInitializationExtension"> <xs:sequence>
<xs:element name="SecondaryOriginUrl" type="xs:string" minOccurs="0"/>
</xs:sequence> </xs:complexType>
URL: https://api.mastercard.com/masterpass/v6/merchant-initialization—Sample Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <MerchantInitializationRequest> <OAuthToken>oauth_demo_token4sj4x6f1eqka2ib2f1nzd1ib2ivvjx16a</OAuthToken> <OriginUrl>http://localhost:8080</OriginUrl> <ExtensionPoint> <SecondaryOriginUrl>http://localhost:8080</SecondaryOriginUrl> </ExtensionPoint> </MerchantInitializationRequest>
V6/merchant-initialization—XML Schema Response <?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> V6/ MerchantInitialization—Sample Response <MerchantInitializationResponse> <OAuthToken>4c7b34cc63a68282bba77a4b34f0192fcb2268fb</OAuthToken> </MerchantInitializationResponse> V6—MerchantInitializationRequest XML Details MerchantInitialization
Request XML Element Description Type Min–Max
MerchantInitializationRe quest
Root Element XML -
MerchantInitialization
Request XML Element Description Type Min–Max
MerchantInitializationRe quest
OAuthToken Request Token
(oauth_token) returned by call to the request_token API
-
OriginUrl Identifies the URL of the page that will initialize the Lightbox.
string NA
ExtensionPoint Reserved for future enhancement. Optional
Any SecondaryOriginUrl Identifies the domain URL
of the outer/parent web page. This optional field should only be used when the Lightbox will be invoked from a frame that’s on a merchant site, and when that frame is of a different domain than that of the merchant site, like for a service provider.
string NA
MerchantInitialization
Response 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 -
ExtensionPoint Elements
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
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—Sample <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 Service
This section provides description on the Shopping Cart parameters.
Shopping Cart Parameters
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 Parameter Details
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_m
ethod
oauth signature method RSA-SHA1 oauth_consumer_ke
y
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
Signature Base String Example
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 OAuth Samples
HTTP Request Example POST /masterpass/v6/shopping-cart HTTP/1.1 Authorization: OAuth realm="eWallet",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b047 6c% 21414f4859446c4a366c726a327474695545332b353049303d",oauth_signature_method="RSA- SHA1",oauth_nonce="DEAEB1CD- CA03-405D-A7B4- B4263CB5A305",oauth_timestamp="1380049711",oauth_version="1.0",oauth_body_hash="8K 9uhveZjVdZW8AIYiXpR70KCtk% 3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C8t6PlW8xTrDob0WzWJ5% 2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zravb02oqTrVQH3Zlx5fi4o0u2x xqrDwHZvbhjPgwByBRmE% 2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D"
Shopping Cart V6—XML Schema <xs:complexType name="ShoppingCart"> <xs:sequence>
<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="ShoppingCartRequest"> <xs:sequence>
<xs:element name="OAuthToken" type="xs:string"/> <xs:element name="ShoppingCart" type="ShoppingCart"/> <xs:element name="ExtensionPoint" type="ShoppingCartRequestExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:element name="ShoppingCartRequestExtensionPoint" type="ShoppingCartRequestExtensionPoint"/> <xs:complexType name="ShoppingCartRequestExtensionPoint"> <xs:sequence>
<xs:element name="SecondaryOriginUrl" type="xs:string" minOccurs="0"/> </xs:sequence>
<xs:anyAttribute/> </xs:complexType>
<xs:element name="ExtensionPoint" type="ExtensionPoint"/> <xs:complexType name="ExtensionPoint">
<xs:sequence>
<xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/> </xs:sequence>
<xs:anyAttribute/> </xs:complexType>
Shopping Cart V6 XML Details
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 -
ExtensionPoint Reserved for future enhancement. Optional
Any -
ExtensionPoint SecondaryOriginUrl Identifies the domain URL of the outer/parent web page. This optional field should only be used when the Lightbox will be invoked from a frame, that is, on a merchant site and when that frame is of a different domain than that of the merchant site, like for a service provider.
String NA
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, for example, USD 119.00 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 OAuth Samples
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, for example, USD 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 -
ShoppingCartRespons e
Element Description Type Min– Max
OAuthToken Request Token
(oauth_token) returned by