Service Provider File and API Onboarding Model

Service Provider Account Registration

1. Navigate to https://masterpass.com/SP/Merchant/Home. On the right-hand side of the page, select your country and click the Create an Account button.
2. A modal window will appear. Submit your invitation code and click Continue.
3. A popup window will ask if you are registering as a merchant or as a service provider. Select Service Provider and click Continue.

4. Next, you are required to complete the three-step Account Registration process.

   4a. In the first step, Enter Account Information, fill out the fields to create your service provider account profile. Click Continue.

   4b. Complete the second step of your Account Registration by selecting and answering two security questions. Click Continue.

   4c. Finish the Account Registration process by filling out the fields in the Enter Business Information step. Click Finish.

Optional - Service Provider Sets Merchant Shipping Locations

1. If any of your merchants ship physical goods, you can set up shipping location profiles to specify where they can ship. To create a new shipping location profile, log into your Service Provider Account and click Shipping Profiles in the navigation.
2. Click the Add Shipping Profile button.
3. Select your organization and create a name for your new shipping location profile.
4. Select a region from the list shown below. All countries in the region are automatically selected. To deselect a country, click the corresponding orange arrow for that region and uncheck the box next to the country to remove.
5. Click the checkbox in the top right to set this profile as your default shipping profile.
6. Click the Save button.

Add Developer(s) to Service Provider Profile

1. Next, you must add the developer(s) who will integrate MasterPass on behalf of your merchant(s). Log into your Service Provider Account and click the Developers item in the navigation menu.
2. Click the Add a Developer button.
   

3. In the modal that appears, select An Internal or Contracted Developer and click Next. The window will then present a form that collects contact information for the developer. Fill out this form and click Complete. The developer will receive an email containing instructions to complete their account registration. See the Developer Account Registration step for more details.

   3a. Optional: To invite another administrator to the project, select I'm not sure and click the Next button. To proceed with the invitation, click the Do this now button; otherwise, click Complete. If you did choose to add another administrator, you will be presented with a form that collects the administrator's contact information. After you submit the form, the administrator will receive an email containing instructions to complete their account registration.

Service Provider Approves Key (requires developer to add consumer key)

1. The service provider approves the key by logging into their Service Provider Account and clicking the Key Management navigation item. The service provider selects the developer that created the key request by clicking the corresponding orange arrow.
2. The service provider can then view any pending keys created by that developer. Click the Approve button to approve the pending key. The developer will receive email confirmation that the key was approved.

File-Based Onboarding

Service providers can upload XML files to add, update, or delete merchant records. Use the file templates referenced here - schema files and swagger file? and view the sample below to upload and create a project.

Create Merchant Record

1. Sign into your Developer Account*. Navigate to the Merchant File Upload menu item.

2. Click the Upload button in the top right.

3. First, you must add a merchant record. All Merchant elements shown below (SPMerchantId, Action, Profile, CheckoutBrand) are required when adding a new merchant. Set the Action to C.

   <MerchantUpload>
       <Merchant>
           <SPMerchantId>SPMerchantId1</SPMerchantId>
           <Action>C</Action>
           <Profile>
               <Name>SPMerch58401</Name>
               <DoingBusAs>SPMerch58401</DoingBusAs>
               <Address>
                   <City>SPMerch58401</City>
                   <Country>US</Country>
                   <Line1>898 SPMerch58401</Line1>
                   <PostalCode>78090</PostalCode>
               </Address>
               <Phone>
                   <CountryCode>1</CountryCode>
                   <Number>3734517671</Number>
               </Phone>
               <Acquirer>
                   <Id>292978156</Id>
                   <Name>QATESTACQ</Name>
                   <AssignedMerchantId>MCQA1</AssignedMerchantId>
               </Acquirer>
           </Profile>
           <CheckoutBrand>
               <Name>SPMerch58401</Name>
               <DisplayName>SPMerch58401</DisplayName>
               <ProductionUrl>https://SPMerch58401.com</ProductionUrl>
               <SandboxUrl>https://SPMerch58401.com</SandboxUrl>
           </CheckoutBrand>
       </Merchant>
   </MerchantUpload>

4. To upload your XML file, click the Upload button.

5. Click Choose File to select your XML file. Enter a brief description of the file, and click the Upload button.

6. When the file is finished processing, a message will display, indicating the number of successful and failed records processed. You will also receive an email notifying you that the file has been processed.

7. Click the Download Result File button to view the results of the XML file processing. This file contains the merchant ID and checkout identifier for each uploaded merchant.

Optional - Add Reward Program

1. You may add a reward program for customers to use during MasterPass transactions. Please note that this feature is only available to MasterPass consumers outside of the United States.

   <MerchantUpload>
       <Merchant>
           <SPMerchantId>SPMerchantId1</SPMerchantId>
           ...
           <RewardProgram>
               <Name>RAMATSR9</Name>
               <Id>RAMATSR9</Id>
               <LogoUrl>http://www.mastercard.us/_globalAssets/img/nav/navl_logo_mastercardcom.png</LogoUrl>
           </RewardProgram>
           ...
       </Merchant>
   </MerchantUpload>

Optional - Add 3D-S Authentication

1. Add 3D-S authentication to this merchant account to allow your merchant to complete the 3-D Secure protocol during MasterPass transactions.

   NOTE: You may not have two Merchant Acquirers with both the same currency and the same CardBrand.

   <MerchantUpload>
       <Merchant>
           <SPMerchantId>SPMerchantId1</SPMerchantId>
           ...
           <AuthOption>
               <CardBrand>MASTER_CARD</CardBrand>
               <Type>ALL_TRANSACTIONS</Type>
           </AuthOption>
           <MerchantAcquirer>
               <Acquirer>
                   <Id>523078</Id>
                   <Name>CartaSI</Name>
                   <AssignedMerchantId>001</AssignedMerchantId>
               </Acquirer>
               <MerchantAcquirerBrand>
                   <CardBrand>MASTER_CARD</CardBrand>
                   <Currency>EUR</Currency>
               </MerchantAcquirerBrand>
           </MerchantAcquirer>
           ...
       </Merchant>
   </MerchantUpload>

Optional - Validate XML Files Before Submitting

1. If you prefer, you may verify your file submission for schema and business rules validation before uploading it. This will allow you to identify and fix any errors before submitting your file for processing. Click the Validate File button, select your file, and click Validate Now.

   1a. If your file successfully follows all rules, you will receive the message "Validation complete, no errors found."

   1b. Otherwise, you will be instructed to fix your error(s) and resubmit the file. To view the errors, click the Download Result File button.

   XML Schema Validation Error Message Example

   <MerchantDownload>
       <Summary>
           <ErrorText>1337: String Length for
   Merchant_Upload.MerchantAcquirer.Acquirer.Name needs to be greater than 1 and
   less than or equal to 250 characters</ErrorText>
       </Summary>
   </MerchantDownload>

   Business Rule Error Codes

   Error Codes	Description	Sample Error Message
   VBMU0100	Validate that a provided checkout brand data element exists.	VBMU0100: minimum of one checkoutBrand required : merchant-spMerchantId=STGQA09
   VBMU0101	Validate that a merchant with action code "C" does not include any brandings with checkout identifiers.	VBMU0101: checkoutBrand cannot include checkout identifiers on create : checkoutId=a4a6w4vnkdeazi6c6ynxk1i6cdd6e2aki
   VBMU0102	Validate that a provided checkout identifier exists when using Action Code "U" within CheckoutBrandĘdata element.	VBMU0102: checkoutBrand does not exist : checkoutId=a4d6x344fquvhi8ix0 v6n1i8udwvar1zv6
   VBMU0110	For Merchant Action Code “U” and Merchant Acquirer Action Code “C," validate the merchant acquirer doesn’t exist in Cardinal Commerce.	VBMU0110: invalid merchant acquirer actionCode during create : actionCode=U
   VBMU0111	For Merchant Action Code “U” and Merchant Acquirer Action Codes “U” or “D," validate the merchant acquirer does exist in Cardinal Commerce.	VBMU0111: invalid merchant acquirer action code: U or D
   VBMU0112	Validate Profile data element exists in the MerchantUpload XML file.	VBMU0112: merchant create requires profile for spMerchantId=STGQA09
   VBMU0120	Validate Reward Program Name is Unique	VBMU0120: reward program name must be unique: RAMAQA312, spMerchantId=STGQA09
   VBMU0121	Validate Reward Program ID is Unique	VBMU0121: reward program id must be unique: RAMAQA312, spMerchantId=STGQA09
   VBMU0130	Validate a Merchant Acquirer is provisioned in Cardinal for a specified CardBrand.	VBMU0130: no merchant acquirer for cardbrand type=MAESTRO
   VBMU0140	Validate SPMerchantID is Unique when applying Merchant Action Code of “C.”	VBMU0140: merchantId already exists for serviceProviderId=305960760 and spMerchantId=STGQA03
   VBMU0141	Validate Merchant Acquirer ID is unique when applying Merchant Action Code of “C.”	VBMU0141: invalid merchant acquirer actionCode=C : acquirer record already exists : acquirerId=523078 assignedMerchantId=001test cardBrand=MASTERCARD currencyCode=EUR
   VBMU0142	Validate Merchant Acquirer ID exists in Cardinal Commerce.	VBMU0142: acquirer id does not exist : id=88848888, cardBrand=MASTERCARD
   VBMU0150	Validate SPMerchantID exists for Merchant Action Codes "U" or "D".	VBMU0150: merchant not found for update or delete
   VBMU0160	Validate the SPMerchantID is alphanumeric and less than 25 characters.	VBMU0160: invalid assignedMerchantId=STGAPI21_******5681M, must be alpha-numeric and less than 25 characters in length
   VBMU0170	Validate the Merchant Acquirer CurrencyCode is supported by Cardinal Commerce.	VBMU0170: unsupported currency code : USD
   VBMU0171	Validate two merchant acquirers of the same CardBrand are not configured to support the same currency by Cardinal Commerce.	VBMU0171: acquirer card brand currency code pairing must be unique

Single Merchant API Onboarding

Services providers who have already completed the File-Based Onboarding step at least once have the option to use API-based onboarding to create, update, and delete merchant records directly to production. Providers may use the Single Merchant API Service, along with a production consumer key and merchant checkout id to update merchant records in real time.

1. After your XML file from the File-Based Onboarding process has been submitted, confirm that an Open Feed Project appears at the top of the project list of your Developer Account.
2. Get the Project ID from the Open Feed Project.
3. Using the same schema as you used in the File-Based Onboarding, create your XML file. Only a single merchant may be added or updated at a time.
4. Follow the example shown below to make a Single Merchant API service call.

Use the following parameters to make your HTTP request:

• checkoutproject: Your Project ID from Step 2. Use the URL format https://api.mastercard.com/masterpasspsp/v6/checkoutproject/projectID/file.
• oauth_body_hash: SHA1 hash of the message body.
• oauth_consumer_key: Your consumer key that was generated during the onboarding process.
• oauth_nonce: Unique alphanumeric string generated from code.
• oauth_signature_method: OAuth signature method. Value should be RSA-SHA1.
• oauth_timestamp: Current timestamp.
• oauth_version: OAuth version. Value should be 1.0.

Signature Base String - Single Merchant API

POST&https%3A%2F%2F.api.mastercard.com%2Fmasterpasspsp%2Fv6%2Fcheckoutproject%2
F[0-9]+%2Ffile&oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_ke%3DcLb0
tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a32747469
5545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4-
B4263CB5A305%26oauth_signature_method%3DRSASHA1%26oauth_timestamp%3D1380049711%26oauth_version%3D1.0

HTTP Request Example - Single Merchant API

POST&https%3A%2F%2Fapi.mastercard.com%2Fitf%2Fmasterpasspsp%2Fv6%2Fcheckoutproj
ect%2F285415568%2Ffile&oauth_body_hash%3DCWrePW5A%252BKMde7DxI5mBp
NVr%252Fok%253D%26oauth_consumer_key%3DewdIBgRu1i6uCoFjuWGU4BNGDb0Udvh26N_mYah6
8efd62f9%252141496b7a452f35764d715752755579436b70467871476f3d%26oauth_nonce%3D1
7157164231493%26oauth_signature_method%3DRSASHA1%26oauth_timestamp%3D1432749165%26oauth_version%3D1.0

Merchant Upload Request - Single Merchant API

<?xml version="1.0" encoding="UTF-8"?>
<MerchantUpload>
 <Merchant>
 <SPMerchantId>STGQA09</SPMerchantId>
 <Action>C</Action>
 <CheckoutBrand>
 <Name>STGQA09</Name>
 <DisplayName>STGQA09</DisplayName>
 <ProductionUrl>https://STGQA09.com</ProductionUrl>
  <SandboxUrl>https://STGQA09.com</SandboxUrl>
 <LogoUrl>http://www.mastercard.us/_globalAssets/img/nav/-
navl_logo_mastercardcom.png</LogoUrl>
 </CheckoutBrand>
 </Merchant>
</MerchantUpload>

Optional - Single Merchant API Validation

If desired, service providers may also use the Validate Merchant API Service to verify their submissions. This will allow you to identify and fix any errors before submitting your file for processing. Use the following sample code to assist you in making your Validation API call.

Signature Base String - Single Merchant API Validation

POST&https%3A%2F%2F.api.mastercard.com%2Fmasterpasspsp%2Fv6%2Fcheckoutproject%2
F[0-9]+%2Ffile&oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_ke%3DcLb0
tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a32747469
5545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4-
B4263CB5A305%26oauth_signature_method%3DRSASHA1%26oauth_timestamp%3D1380049711%26oauth_version%3D1.0

HTTP Request Example - Single Merchant API Validation

POST&https%3A%2F%2Fapi.mastercard.com%2Fitf%2Fmasterpasspsp%2Fv6%2Fcheckoutproj
ect%2F285415568%2Ffile%2Fvalidation&oauth_body_hash%3DCWrePW5A%252BKMde7DxI5mBp
NVr%252Fok%253D%26oauth_consumer_key%3DewdIBgRu1i6uCoFjuWGU4BNGDb0Udvh26N_mYah6
8efd62f9%252141496b7a452f35764d715752755579436b70467871476f3d%26oauth_nonce%3D1
7157164231493%26oauth_signature_method%3DRSASHA1%26oauth_timestamp%3D1432749165%26oauth_version%3D1.0

Merchant Upload Response - Validation

<?xml version="1.0" encoding="UTF-8"?>
<ValidateFileResponse>
 <ValidatedMerchant>
 <MerchantId>STGQA09</MerchantId>
 <ErrorText>VBMU0140: merchantId already exists for
serviceProviderId=285415466 and spMerchantId=STGQA09</ErrorText>
 </ValidatedMerchant>
</ValidateFileResponse>