MCSCommerceWeb 1.1.4

MCSCommerceWeb 1.1.4

×

由 Bret Deasy，Cesar Oyarzun，Sahil Ishar，Bret Deasy，nathaniel payne，Deepak Divakaran 维护。

MCSCommerceWeb 1.1.4

  • 由
  • Bret Deasy

MCSCommerceWeb

概览

MCSCommerceWeb 是一个轻量级框架，用于将商户与 EMV Secure Remote Commerce 和 Mastercard 的基于 Web 的 SRC-Initiator 集成，并对现有的 Masterpass 集成具有向后兼容性。 MCSCommerceWeb 便于启动结账体验并在完成后将交易结果返回给商户。

配置在商户门户上

在门户上正确配置这些值非常重要。如果这些值未以正确格式配置，商户应用程序将无法成功结账

callbackUrl 必须配置为 URL Schemes。以下是名为 FancyShop 的示例商户应用程序的 callbackUrl 格式示例

  • callbackUrl 的示例格式: fancyshop://
  • 渠道: IOS

安装

使用CocoaPods

要将MCSCommerceWeb添加到您的Xcode项目中，请将以下内容添加到项目的Podfile中

pod 'MCSCommerceWeb'

配置

在实例化MCSCommerceWeb时，需要提供一个MCSConfiguration对象。

MCCConfiguration有4个新必需属性和一个可选属性

  • locale：这是处理交易时使用的区域设置
  • checkoutId：在上线过程中分配给商家的唯一标识符
  • checkoutUrl：用于加载结账体验的URL。 注意：在沙盒环境中进行测试时，使用 https://sandbox.masterpass.com/routing/v2/mobileapi/web-checkout 。对于生产环境，使用 https://masterpass.com/routing/v2/mobileapi/web-checkout 。
  • callbackScheme：这必须匹配为该商家配置的callbackUrl的方案组件。此值用于从WKWebView返回
  • allowedCardTypes：此商家支持的支付网络（例如主体、visa、amex）
  • presentingViewController：可选的ViewController，可以选择提供和展示，而不是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];

结账按钮

通过将MCSCheckoutButton添加到视图中来启动交易。

// 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按钮图像

对于希望提供替代的 SOURC结账可选方法的商家，可以通过添加额外的withImage:参数来使用

  • 在MCSCheckoutButtonManager.h类中添加了(MCSCheckoutButton *)checkoutButtonWithDelegate:(id<MCSCheckoutDelegate>)delegate withImage:(UIImage *)image
  • (MCCMasterpassButton * _Nullable)getMasterPassButton:(id<MCCMerchantDelegate>) merchantDelegate withImage:(UIImage *)image 被添加到 MCCMerchant.h 类中
  • (MCSCheckoutButton *_Nonnull)checkoutButtonWithDelegate:(id<MCSCheckoutDelegate>_Nonnull)delegate withImage:(UIImage *_Nonnull)image NS_SWIFT_NAME(getCheckoutButton(withDelegate:withImage:)) 被添加到 MCSCommerceWeb.h 类中
// 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:

MCSCheckoutDelegate 提供了以下方法

// 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;

当用户触摸 MCSCheckoutButton 时，将检索此交易的 MCSCheckoutRequest。

Checkout Request

// Swift
func getCheckoutRequest(withHandler: @escaping (MCSCheckoutRequest) -> Void)
// Objective-C
- (void)checkoutRequestForTransaction:(nonnull void(^)(MCSCheckoutRequest * _Nonnull checkoutRequest))handler;

checkoutRequest: 包含完成结账所需特定交易参数的数据对象。此请求还可以覆盖现有的商户配置。

以下为所需和可选字段

参数 类型 必需 描述
allowedCardTypes 数组 是 接受此交易的卡类型集合
amount 十进制数 是 授权的交易总额
cartId 字符串 是 商户为此交易的唯一标识符
callbackUrl 字符串 否 用于将信息发送回商户应用程序的URL
cryptoOptions 数组 否 此商户接受的密文格式
cvc2Support 布尔值 否 启用或禁用对CVC2卡安全性的支持
shippingLocationProfile 字符串 否 此商户可用的发货位置
suppress3Ds 布尔值 否 启用或禁用3DS验证
suppressShippingAddress 布尔值 否 启用或禁用发货选项。通常对于数字商品或服务，此值将设为 true
unpredictableNumber 字符串 否 对于标记化交易，必须提供 unpredictableNumber 以生成密文
validityPeriodMinutes 整数 否 生成的密文的过期时间（分钟）

使用这些参数实现结账

// 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);
}

您还可以直接调用 checkout 来进行结账而不使用按钮方法，但请确保在之前设置您的代理

// 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;

交易结果通过获取 MCSCheckoutButton 时提供的 MCSCheckoutDelegate 返回给应用程序。

// 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
    }
}

从MCCMerchant迁移

注意：在 MCSCommerceWeb 中的 MCCMerchant API 已弃用，将在后续版本中删除。建议迁移到上述 API。

MCSCommerceWeb 为 MCCMerchant 提供API兼容性。现有使用 MCCmerchant 的应用可以轻松迁移到 MCSCommerceWeb 而需做最小修改。在从 MCCMerchant 迁移时，请考虑以下内容。

接口和类

此 SDK 包含了 MCCMerchant 接口，但 import 语句必须更新为使用 MCSCommerceWeb 模块。

// 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有4个新必需属性和一个可选属性

  • checkoutId：创建商户开发者配置文件时生成的商户标识符。注意：此值已从 MCCCheckoutRequest 移动。
  • allowedCardTypes：此商户支持的支付网络（例如 master、visa、amex）。注意：此值已从 MCCCheckoutRequest 移动。
  • callbackScheme：用于将数据返回到本应用的方案。这是在 info.plist 中的 URL Schemes 中配置的值。
  • checkoutUrl：用于加载结账体验的 URL。注意：如果您正在迁移到 MCSCommerceWeb，但仍然计划使用 Masterpass 进行结账，您仍然需要提供此 URL。*presentingViewController：可选的 ViewController 可以传递并展示，而不是普通的 keyWindow RootViewController
环境 URL
Masterpass 沙盒 https://sandbox.masterpass.com/routing/v2/mobileapi/web-checkout
Masterpass 生产 https://masterpass.com/routing/v2/mobileapi/web-checkout
处理结账响应
// MCCMerchant.h
+ (BOOL)handleMasterpassResponse:(NSString *_Nonnull)url delegate:(id<MCCMerchantDelegate> _Nonnull)merchantDelegate;

handleMasterpassResponse:delegate 不再有任何效果。MCSCommerceWeb 使用 WKWebView 替代 SFSafariViewController，并且使用 MCCDelegate 直接处理结账响应。任何结账调用中提供的 MCCDelegate 将是接收结账响应的代理。

添加支付方式
// MCSCommerceWeb.h
- (MCCPaymentMethod *_Nonnull)addPaymentMethod;

addMasterpassPaymentMethod:withCompletionBlock: 不再需要被调用。MCSCommerceWeb 现在提供了 addPaymentMethod: 函数来支持支付方式。它始终返回具有以下属性的相同支付方式

  • paymentMethodName : 点击支付
  • paymentMethodLogo : 作为 UIImage 的 SRC 图标

此支付方式或任何其他支付方式都可以与 paymentMethodCheckout: 结合使用来启动标准的结账流程（参见下一部分）。

支付方式结账
// MCSCommerceWeb.h
- (void)paymentMethodCheckout:(id<MCSCheckoutDelegate> _Nonnull)delegate request:(MCSCheckoutRequest *_Nonnull)request;

paymentMethodCheckout: 不再需要调用。MCSCommerceWeb 提供了 paymentMethodCheckout:delegate:request:，它将使用 MCSCheckoutDelegate 处理响应来启动标准的 SRC 结账流程。

旧函数 新函数
+ (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