MCSCommerceWeb

• Overview
• Configuration on Merchant Portal
• Installation
• Configuration
• Checkout Button
  • Checkout Request
• Transaction Result
• Migrating from MCCMerchant
  • Interfaces and classes
  • Add Payment Method
  • Payment Method Checkout

Overview

MCSCommerceWeb is a lightweight framework used to integrate Merchants with EMV Secure Remote Commerce and Mastercard's web-based SRC-Initiator with backward compatibility for existing Masterpass integrations. MCSCommerceWeb facilitates the initiation of the checkout experience and returns the transaction result to the Merchant after completion.

Configuration on Merchant Portal

It is very important to configure these values properly on the portal. If these values are not configured in proper format, merchant application will not be able to do successful checkout

callbackUrl must be configured as URL Schemes. Below is an example format of callbackUrl for a sample merchant application named FancyShop

• Example format of callbackUrl: fancyshop://
• Channel: IOS

Installation

CocoaPods

To include MCSCommerceWeb in your Xcode project, include the following in your project's Podfile:

pod 'MCSCommerceWeb'

Configuration

When instantiating MCSCommerceWeb, an MCSConfiguration object needs to be provided.

MCCConfiguration has 4 new required properties and one optional property

• locale: This is the locale in which the transaction is processing
• checkoutId: The unique identifier assigned to the merchant during onboarding
• checkoutUrl: The URL used to load the checkout experience. Note: when testing in the Sandbox environment, use https://sandbox.masterpass.com/routing/v2/mobileapi/web-checkout . For Production, use https://masterpass.com/routing/v2/mobileapi/web-checkout .
• callbackScheme: This must match the scheme component of the callbackUrl configured for this merchant. This value is required to redirect back from the WKWebView
• allowedCardTypes : The payment networks supported by this merchant (e.g. master, visa, amex).
• presentingViewController : optional ViewController can be passed and presented instead of the vanilla keyWindow RootViewController

// Swift
let locale = Locale(identifier: "en_us")
let checkoutId = "1d45705100044e14b52e71730e71cc5a"
let checkoutUrl = "https://masterpass.com/routing/v2/mobileapi/web-checkout";
let callbackScheme = "fancyshop";
let allowedCardTypes = [.master, .visa , .amex]
    
let commerceConfig = MCSConfiguration(
    locale: locale,
    checkoutId: checkoutId,
    checkoutUrl: checkoutUrl,
    callbackScheme: callbackScheme,
    allowedCardTypes: allowedCardTypes,
            presenting: viewController)
)
    
let commerceWeb = MCSCommerceWeb.sharedManager()
commerceWeb.setConfiguration(withConfiguration: commerceConfig)

// Objective-C
NSLocale *locale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_us"];
NSString *checkoutId = @"1d45705100044e14b52e71730e71cc5a";
NSString *checkoutUrl = @"https://masterpass.com/routing/v2/mobileapi/web-checkout";
NSString *callbackScheme = @"fancyshop";
NSSet *allowedCardTypes = [NSSet setWithObject:MCSCardTypeMaster, MCSCardTypeVisa, MCSCardTypeAmex];
MCSConfiguration *config = [[MCSConfiguration alloc] initWithLocale:locale
                                                         checkoutId:checkoutId
                                                        checkoutUrl:checkoutUrl
                                                     callbackScheme:callbackScheme
                                                   allowedCardTypes:allowedCardTypes
                                                   presentingViewController:presentedViewController];

MCSCommerceWeb *commerceWeb = [MCSCommerceWeb sharedManager];
[commerceWeb initWithConfiguration:config];

Checkout Button

Transactions are initiated by adding MCSCheckoutButton to the view.

// Swift
// SomeViewController.swift
let button = commerceWeb.getCheckoutButton(withDelegate:checkoutDelegate)
button.addToSuperview(superview: buttonContainer)

// Objective-C
// SomeViewController.m
MCSCheckoutButton *button = [commerceWeb checkoutButtonWithDelegate:checkoutDelegate];
[button addToSuperview:buttonContainer];

SRC Button Image

For merchants who would like to provide an alternate SRC checkout optional methods with additional withImage: parameter have been added

• (MCSCheckoutButton *)checkoutButtonWithDelegate:(id<MCSCheckoutDelegate>)delegate withImage:(UIImage *)image added to MCSCheckoutButtonManager.h class,
• (MCCMasterpassButton * _Nullable)getMasterPassButton:(id<MCCMerchantDelegate>) merchantDelegate withImage:(UIImage *)image added to MCCMerchant.h class
• (MCSCheckoutButton *_Nonnull)checkoutButtonWithDelegate:(id<MCSCheckoutDelegate>_Nonnull)delegate withImage:(UIImage *_Nonnull)image NS_SWIFT_NAME(getCheckoutButton(withDelegate:withImage:)) added to MCSCommerceWeb.h class

// Swift
// Swift
// SomeViewController.swift
let button = commerceWeb.getCheckoutButton(withDelegate:checkoutDelegate, withImage:image)
button.addToSuperview(superview: buttonContainer)

//Objective-C
// SomeViewController.m
MCSCheckoutButton *button = [commerceWeb checkoutButtonWithDelegate:checkoutDelegate withImage:image];
[button addToSuperview:buttonContainer];

withDelegate:

The MCSCheckoutDelegate provided has the following methods:

// MCSCheckoutDelegate
// Swift
// Fetches the checkout request object required to initiate this transaction.
func getCheckoutRequest(withHandler: @escaping (MCSCheckoutRequest) -> Void)

// Notifies the delegate when the transaction has completed
func checkoutCompleted(withRequest request: MCSCheckoutRequest, status: MCSCheckoutStatus, transactionId: String?)

// MCSCheckoutDelegate
// Objective-C
// Fetches the checkout request object required to initiate this transaction.
- (void)checkoutRequestForTransaction:(nonnull void(^)(MCSCheckoutRequest * _Nonnull checkoutRequest))handler;

//Notifies the delegate when the transaction has completed
- (void)checkoutRequest:(MCSCheckoutRequest *)request didCompleteWithStatus:(MCSCheckoutStatus)status forTransaction:(NSString * _Nullable)transactionId;

When the user touches up on MCSCheckoutButton, MCSCheckoutRequest for this transaction is retrieved.

Checkout Request

// Swift
func getCheckoutRequest(withHandler: @escaping (MCSCheckoutRequest) -> Void)

// Objective-C
- (void)checkoutRequestForTransaction:(nonnull void(^)(MCSCheckoutRequest * _Nonnull checkoutRequest))handler;

checkoutRequest: Data object with transaction-specific parameters needed to complete checkout. This request can also override existing merchant configurations.

Here are the required and optional fields:

Parameter	Type	Required	Description
allowedCardTypes	Array	Yes	Set of all card types accepted for this transaction
amount	Decimal	Yes	The transaction total to be authorized
cartId	String	Yes	Merchant's unique identifier for this transaction
callbackUrl	String	No	URL used to communicate back to the merchant application
cryptoOptions	Array	No	Cryptogram formats accepted by this merchant
cvc2Support	Boolean	No	Enable or disable support for CVC2 card security
shippingLocationProfile	String	No	Shipping locations available for this merchant
suppress3Ds	Boolean	No	Enable or disable 3DS verification
suppressShippingAddress	Boolean	No	Enable or disable shipping options. Typically for digital goods or services, this will be set to true
unpredictableNumber	String	No	For tokenized transactions, unpredictableNumber is required for cryptogram generation
validityPeriodMinutes	Integer	No	The expiration time of a generated cryptogram, in minutes

The implementation of the checkout with these parameters:

// Swift
func getCheckoutRequest(withHandler: @escaping (MCSCheckoutRequest) -> Void) {
    let checkoutRequest = MCSCheckoutRequest()
    checkoutRequest.amount = NSDecimalNumber(string: String(shoppingCart.total))
    checkoutRequest.currency = sdkConfig.currency
    checkoutRequest.cartId = shoppingCart.cartId
    checkoutRequest.allowedCardTypes = [.master,.visa]
    checkoutRequest.suppressShippingAddress = sdkConfig.suppressShipping
    checkoutRequest.callbackUrl = "fancyshop://"
    checkoutRequest.unpredictableNumber = "12345678"
        
    let cryptoOptionVisa = MCSCryptoOptions()
    cryptoOptionVisa.cardType = "visa"
    cryptoOptionVisa.format = ["TVV"]
    
    let cryptoOptionMaster = MCSCryptoOptions()
    cryptoOptionMaster.cardType = "master"
    cryptoOptionMaster.format = ["ICC,UCAF"]
    
    checkoutRequest.cryptoOptions = [cryptoOptionMaster,cryptoOptionVisa]
        
    withHandler(checkoutRequest)
}

// Objective-C
- (void)checkoutRequestForTransaction:(nonnull void(^)(MCSCheckoutRequest * _Nonnull checkoutRequest))handler {
    MCSCheckoutRequest *checkoutRequest = [[MCSCheckoutRequest alloc] init];
    checkoutRequest.amount = [[NSDecimalNumber alloc] initWithString:shoppingCart.total];
    checkoutRequest.currency = sdkConfig.currency
    checkoutRequest.cartId = shoppingCart.cartId
    checkoutRequest.allowedCardTypes = [NSSet setWithObjects:MCSCardTypeMaster, MCSCardTypeVisa, nil];
    checkoutRequest.suppressShippingAddress = sdkConfig.suppressShipping;
    checkoutRequest.callbackUrl = @"fancyshop://";
    checkoutRequest.unpredictableNumber = @"12345678";
    
    MCSCryptoOptions *cryptoOptionMaster = [[MCSCryptoOptions alloc] init];
    cryptoOptionMaster.cardType = MCSCardTypeMaster;
    cryptoOptionMaster.format = @[MCSCryptoFormatICC, MCSCryptoFormatUCAF];
    
    checkoutRequest.cryptoOptions = @[cryptoOptionMaster];
    
    handler(checkoutRequest);
}

You can also call checkout directly with checkout and not use button method, make sure you set your delegate before

// Swift
func merchantCheckout() -> Void) {
    let checkoutRequest = MCSCheckoutRequest()
    checkoutRequest.amount = NSDecimalNumber(string: String(shoppingCart.total))
    checkoutRequest.currency = sdkConfig.currency
    checkoutRequest.cartId = shoppingCart.cartId
    checkoutRequest.allowedCardTypes = [.master,.visa]
    checkoutRequest.suppressShippingAddress = sdkConfig.suppressShipping
    checkoutRequest.callbackUrl = "fancyshop://"
    checkoutRequest.unpredictableNumber = "12345678"
        
    let cryptoOptionVisa = MCSCryptoOptions()
    cryptoOptionVisa.cardType = "visa"
    cryptoOptionVisa.format = ["TVV"]
    
    let cryptoOptionMaster = MCSCryptoOptions()
    cryptoOptionMaster.cardType = "master"
    cryptoOptionMaster.format = ["ICC,UCAF"]
    
    checkoutRequest.cryptoOptions = [cryptoOptionMaster,cryptoOptionVisa]
        
    //Call checkout directly
    let commerceWeb = MCSCommerceWeb.sharedManager()
    commerceWeb.setDelegate(self);
    commerceWeb.checkoutReq(checkoutRequest);
}

// Objective-C
- (void)merchantCheckout() {
    MCSCheckoutRequest *checkoutRequest = [[MCSCheckoutRequest alloc] init];
    checkoutRequest.amount = [[NSDecimalNumber alloc] initWithString:shoppingCart.total];
    checkoutRequest.currency = sdkConfig.currency
    checkoutRequest.cartId = shoppingCart.cartId
    checkoutRequest.allowedCardTypes = [NSSet setWithObjects:MCSCardTypeMaster, MCSCardTypeVisa, nil];
    checkoutRequest.suppressShippingAddress = sdkConfig.suppressShipping;
    checkoutRequest.callbackUrl = @"fancyshop://";
    checkoutRequest.unpredictableNumber = @"12345678";
    
    MCSCryptoOptions *cryptoOptionMaster = [[MCSCryptoOptions alloc] init];
    cryptoOptionMaster.cardType = MCSCardTypeMaster;
    cryptoOptionMaster.format = @[MCSCryptoFormatICC, MCSCryptoFormatUCAF];
    
    checkoutRequest.cryptoOptions = @[cryptoOptionMaster];
    //Call checkout directly
    MCSCommerceWeb *commerceWeb = [MCSCommerceWeb sharedManager];
    [commerceWeb setDelegate:self];
    [commerceWeb checkoutWithRequest:checkoutRequest];
}

Transaction Result

// Swift
func checkoutCompleted(withRequest request: MCSCheckoutRequest, status: MCSCheckoutStatus, transactionId: String?)

// Objective-C
- (void)checkoutRequest:(MCSCheckoutRequest *)request didCompleteWithStatus:(MCSCheckoutStatus)status forTransaction:(NSString * _Nullable)transactionId;

The result of a transaction is returned to the application via the MCSCheckoutDelegate provided when retrieving the MCSCheckoutButton.

// Swift
func checkoutCompleted(withRequest request: MCSCheckoutRequest!, status: MCSCheckoutStatus, transactionId: String?) {
    if (transactionId != nil) {
        //comlpete transaction
    }
}

// Objective-C
- (void)checkoutRequest:(MCSCheckoutRequest *)request didCompleteWithStatus:(MCSCheckoutStatus)status forTransaction:(NSString * _Nullable)transactionId {
    if (transactionId != nil) {
        //complete transaction
    }
}

Migrating from MCCMerchant

Note: MCCMerchant APIs are deprecated in MCSCommerceWeb and will be removed in subsequent versions. It is encouraged to migrate to the APIs above.

MCSCommerceWeb provides API compatibility for MCCMerchant. Existing applications using MCCmerchant can easily migrate to MCSCommerceWeb with minimal changes. Consider the following when migrating from MCCMerchant.

Interfaces and Classes

The MCCMerchant interface is included in this SDK, however import statements must update to use the MCSCommerceWeb module.

// Swift
// previous import statement
import MCCMerchant

// current import statement
import MCSCommerceWeb

// Objective-C
// previous
#import <MCCMerchant/MCCMerchant.h>

// current
#import <MCSCommerceWeb/MCSCommerceWeb.h>

MCCConfiguration

MCCConfiguration has 4 new required properties and one optional property

• checkoutId : The merchant identifier generated when created a merchant developer profile. Note: this is moved from MCCCheckoutRequest
• allowedCardTypes : The payment networks supported by this merchant (e.g. master, visa, amex). Note: this is moved from MCCCheckoutRequest
• callbackScheme : The scheme used to return data to this application. This is the value configured in URL Schemes in the info.plist
• checkoutUrl : The URL used to load the checkout experience. Note: if you are migrating to MCSCommerceWeb, but still plan to checkout with Masterpass, you will still need to provide this URL. *presentingViewController : optional ViewController can be passed and presented instead of the vanilla keyWindow RootViewController

Environment	URL
Masterpass Sandbox	https://sandbox.masterpass.com/routing/v2/mobileapi/web-checkout
Masterpass Production	https://masterpass.com/routing/v2/mobileapi/web-checkout

Handle checkout response

// MCCMerchant.h
+ (BOOL)handleMasterpassResponse:(NSString *_Nonnull)url delegate:(id<MCCMerchantDelegate> _Nonnull)merchantDelegate;

handleMasterpassResponse:delegate no longer has any effect. MCSCommerceWeb implements WKWebView instead of SFSafariViewController and the checkout response is handled using MCCDelegate directly. The MCCDelegate provided in any checkout calls will be the delegate that receives the checkout response.

Add Payment Method

// MCSCommerceWeb.h
- (MCCPaymentMethod *_Nonnull)addPaymentMethod;

addMasterpassPaymentMethod:withCompletionBlock: should no longer be called. MCSCommerceWeb now provides the function addPaymentMethod: to support payment method. It always returns the same payment method with the following properties:

• paymentMethodName : Click to Pay
• paymentMethodLogo : The SRC logo as UIImage

This payment method, or any other, can be used with paymentMethodCheckout: to initiate a standard checkout flow (see next).

Payment Method Checkout

// MCSCommerceWeb.h
- (void)paymentMethodCheckout:(id<MCSCheckoutDelegate> _Nonnull)delegate request:(MCSCheckoutRequest *_Nonnull)request;

paymentMethodCheckout: should no longer be called. MCSCommerceWeb provides paymentMethodCheckout:delegate:request: which will initiate the standard SRC checkout flow with the MCSCheckoutDelegate handling the response.

Old Function	New Function
+ (void)addMasterpassPaymentMethod:(id<MCCMerchantDelegate> _Nonnull)merchantDelegate withCompletionBlock:(void(^ __nonnull) (MCCPaymentMethod* _Nullable mccPayment, NSError * _Nullable error))completionHandler;	- (MCCPaymentMethod *_Nonnull)addPaymentMethod;
+ (void)paymentMethodCheckout:(id<MCCMerchantDelegate> _Nonnull) merchantDelegate;	- (void)paymentMethodCheckout:(id<MCSCheckoutDelegate> _Nonnull)delegate request:(MCSCheckoutRequest *_Nonnull)request