要使用 Mangopay Checkout SDK，您需要：
- 一个 Mangopay
ClientId和 API 密钥 - 一个用于注册卡的用户（参见测试 - 支付方式，获取测试卡信息）
- iOS 13 及以上
- Xcode 12.2
- Swift 5.3 及以上
Mangopay Checkout SDK 可以通过 SPM（强烈推荐）或 Cocoapods 安装。
- 打开您的 Xcode 项目，然后转到 *File > Swift Packages > Add Package Dependency*
- 在弹出的对话框中，输入存储库 URL https://github.com/Mangopay/mangopay-ios-sdk
- 通过选中相应的复选框来选择“checkout-ios-sdk”包
- 按照屏幕上的说明完成安装
打开您的podfile并添加
pod 'MangopayCheckoutSDK’
将这些源添加到您的 podfile 之上
source 'https://github.com/CocoaPods/Specs.git'
source 'https://gitlab.com/mangopay/dev/checkout-ios-sdk'
使用您的 ClientId、NethoneMerchantId 初始化 SDK 并选择您的环境（沙盒或生产环境）。
MangopayCheckoutSDK.initialize(clientId: "client_id", profillingMerchantId: "profillingMerchant_id", environment: .sandbox)
| 参数 | 类型 | 描述 |
|---|---|---|
| clientId | String (字符串) | MGPEnvironment |
| profillingMerchantId | String (字符串) | 初始化 Checkout SDK 需要 profilingMerchantId，即使您没有订阅欺诈预防服务。请联系 Mangopay 获取您的标识符。 |
| environment | Environment (环境) | 预期的后端环境。 |
默认值：Environment.SANDBOX
允许的值：Environment.SANDBOX, Environment.PRODUCTION |
🚨 Checkout 具有集成的欺诈分析器，可执行后台检查并收集付款人设备上的数据，以评估交易风险。成功完成卡令牌化后，SDK 会提供一个 fraudProfilerId。在发出 PayIn 请求时，将其作为 ProfilingAttemptReference 添加，以启用欺诈保护。
-
在您的 ViewController 中创建一个 Checkout Sheet 实例
var checkout: MGPPaymentSheet!
-
使用
paymentMethodOptions配置paymentSheet
let paymentMethodOptions = PaymentMethodOptions(
cardOptions: cardOptions,
applePayOptions: applePayOptions,
paypalOptions: paypalOptions
)
2.1 **卡选项配置**
let cardOptions = MGPCardOptions(supportedCardBrands: [.mastercard, .visa, .discover])
卡选项配置参数
| 参数 | 类型 | 描述 |
|---|---|---|
| supportedCardSchemes | Array<[CardType]> (数组<[卡类型]>) | 要为卡支付选项显示的卡计划 |
| cardRegistration | CardRegistration? (卡注册?) | 您可以选择从配置中提供 CardRegistration，或者从回调中提供 |
2.2 ApplePay 选项
let applePayOptions = MGPApplePayOptions(
amount: 10,
delegate: self,
merchantIdentifier: config.merchantID,
merchantCapabilities: .capability3DS,
currencyCode: "USD",
countryCode: "US",
supportedNetworks: [
.masterCard,
.visa
],
requiredBillingContactFields: [.name],
billingContact: contact,
shippingType: .delivery
)
有关 ApplePay 选项参数，请参阅此部分。
2.3 Paypal 选项配置
**let** paypalOptions = MGPPaypalOptions()
Paypal 选项配置参数
| 参数 | 类型 | 描述 |
|---|---|---|
| color | PayPalButton.Color (PayPal按钮.颜色) | PayPal 按钮的颜色。如果未提供，则默认为金色。 |
| edges | PaymentButtonEdges (支付按钮边) | 按钮的边缘。如果未提供，则默认为 softEdges。 |
| label | PayPalButton.Label (PayPal按钮.标签) | 显示在按钮徽标旁边的标签。默认为无标签。 |
- 创建一个支付处理程序/回调
let callback = CallBack(
onPaymentMethodSelected: { paymentMethod in
},
onTokenizationCompleted: { tokenizedData in
},
onCreateCardRegistration: { cardInfo in
},
onPaymentCompleted: { attemptReference, result in
},
onCreatePayment: { paymentMethod, attemptReference in
switch paymentMethod {
case .card(_):
//
case .payPal:
default: return nil
}
},
onCancel: {
},
onError: { error in
}
)
回调参数
| 属性 | 类型 | 描述 |
|---|---|---|
| onPaymentMethodSelected | ((PaymentMethod) -> Void) ((支付方式) -> Void) | 选择付款方式时触发。 |
| onTokenizationCompleted | ((TokenizedCardData) -> Void) ((令牌化卡数据) -> Void) | 卡令牌化完成并返回 CardId 时触发 |
| onCreateCardRegistration | ((MGPCardInfo) async -> MGPCardRegistration?) ((MGPCardInfo) 异步 -> MGPCardRegistration?) | 这使开发人员可以控制在支付会话期间选择创建卡注册。仅当购物者单击卡支付的“支付”按钮时才会被调用 |
| onPaymentCompleted | ((PaymentMethod, String?) async -> Payable?) ((支付方式, String?) 异步 -> 可支付? | 无论结果如何（成功或失败），在交易完成时触发。 |
| onCancelled | () -> Void)? (() -> Void)? | 在 payment sheet 关闭时调用 |
| onError | 当发生内部 Checkout SDK 错误时触发。 |
成功完成卡令牌化后，SDK 会提供一个 fraudProfilerId。在发出 PayIn 请求时，将其作为 ProfilingAttemptReference 添加，以启用欺诈保护。
- 初始化 the PaymentSheet
checkout = MGPPaymentSheet.create(
paymentMethodOptions: paymentMethodOptions,
branding: PaymentFormStyle(),
callback: callback
)
- 呈现支付 Sheet
checkout.present(in: self)
卡元素提供了一个现成的组件，允许您创建自己的卡支付体验并令牌化卡支付详细信息。借助我们的卡元素，您可以轻松地合并自定义支付按钮并控制令牌化过程。
使用卡元素时，您仍然可以受益于实时卡数据验证以及自定义支付表单的能力。
lazy var elementForm: MGPPaymentForm = {
let form = MGPPaymentForm(
paymentFormStyle: PaymentFormStyle(),
supportedCardBrands: [.visa, .mastercard, .maestro]
)
return form
}()
MGPPaymentForm
| 属性 | 类型 | 描述 |
|---|---|---|
| paymentFormStyle | PaymentFormStyle (支付表单样式) | 用于设置支付表单样式的属性。 |
| supportedCardBrands | Array (数组) | 在支付表单上方列出的受支持的卡品牌。 |
**self**.view.addSubview(elementForm)
2.1 创建卡注册对象，如此处所述
2.2 在需要时调用 tokenizeCard()（例如，当单击支付按钮时）
MangopayCoreiOS.tokenizeCard(
form: elementForm,
with: cardRegistration,
presentIn: <presenting_view_controller>
) { respoonse, error in
if let res = respoonse {
//do something
}
if let err = error {
//do something
}
}
**MangopayCoreiOS.tokenizeCard()**
| 属性 | 类型 | 描述 |
|---|---|---|
| form | MangopayCheckoutForm | 支付表单实例 |
| with | MGPCardRegistration | 卡注册对象 |
| presentIn | UIViewController | |
| callBack | typealias MangoPayTokenizedCallBack = ((TokenizedCardData?, MGPError?) -> ()) | 处理支付表单令牌化过程事件的回调 |
**TokenizedCardData**
| 属性 | 类型 | 描述 |
|---|---|---|
| card | CardRegistration (卡注册) | 令牌化卡对象 |
| profilingAttemptReference | String (字符串) | Nethone 提供的尝试引用 |
|
处理 ApplePay 支付 |
要使用 Mangopay Checkout SDK 接受 ApplePay 支付，您需要：
- 在您的 Apple 开发者帐户中创建商家标识符
- 注册和验证您的商家域名
- 创建与您的 merchantId 关联的商家身份证书
- 设置您的服务器，以便与 Apple Pay 进行安全通信并创建商家会话。
- 请联系您的 CSM 以启用 ApplePay
要使用 Mangopay PaymentSheet 接受 Apple Pay 支付，在创建 Checkout 类实例时，您可以选择包含一个 MGPApplePayConfig 对象。这将在您的支付表单中显示 ApplePay 按钮并处理 ApplePay 令牌化过程。
您需要将 Checkout 提供的 ApplePay 支付数据传递到您后端的 Apple PayIn 请求。
有关更多信息，请参阅 Mangopay 文档中的“使用 ApplePay 进行 PayIn”教程。
let applePayConfig = MGPApplePayConfig(
amount: 1,
delegate: self,
merchantIdentifier: "<merchant_id>",
merchantCapabilities: .capability3DS,
currencyCode: "<currency_code",
countryCode: "<country_code",
supportedNetworks: [
.masterCard,
.visa
]
)
let paymentConfig = PaymentMethodConfig(cardReg: cardRegObj, applePayConfig: applePayConfig)
checkout = MGPPaymentSheet.create(
client: mgpClient,
paymentMethodConfig: paymentConfig,
branding: PaymentFormStyle(),
callback: callback
)
| 属性 | 类型 | 描述 | 必需 |
|---|---|---|---|
| amount | Double (双精度浮点数) | 正在支付的金额。 | 是 (Y) |
| delegate | MGPApplePayHandlerDelegate | 事件处理程序。 | 是 (Y) |
| merchantIdentifier | String (字符串) | 商家标识符 | 是 (Y) |
| merchantCapabilities | PKMerchantCapability | 您支持的支付处理协议和卡类型的位字段。 | 是 (Y) |
| currencyCode | String (字符串) | 用于确定此支付请求所用货币的三字母 ISO 4217 货币代码。 | 是 (Y) |
| countryCode | String (字符串) | 商家的两字母 ISO 3166 国家代码。 | 是 (Y) |
| supportedNetworks | Array (数组) | 您支持的支付方式。 | 是 (Y) |
| requiredBillingContactFields | Set (集合) | 否 (N) | |
| billingContact | PKContact | 否 (N) | |
| shippingContact | PKContact | 否 (N) | |
| shippingType | PKShippingType | 否 (N) | |
| shippingMethods | Array (数组) | 否 (N) | |
| applicationData | Data (数据) | 否 (N) | |
| requiredShippingContactFields | Set (集合) | 否 (N) |
extension ViewController: MGPApplePayHandlerDelegate {
func applePayContext(didSelect shippingMethod: PKShippingMethod, handler: @escaping (PKPaymentRequestShippingMethodUpdate) -> Void) {
}
func applePayContext(didCompleteWith status: MangoPayApplePay.PaymentStatus, error: Error?) {
}
}
您可以将注册的卡 (CardId) 用于以下对象的支付
将 Checkout 提供的 Google PaymentData 包含在您的 Google PayIn 中：使用 GooglePay 进行 PayIn
您可以使用以下端点来管理卡
某些支付方式（卡、PayPal）需要或可能需要用户重定向以授权或完成交易。
Checkout SDK 允许您无缝地管理整个支付流程，同时保留对后端交易逻辑的控制。选择支付方式并提供支付详细信息后，使用 onCreatePayment 函数从您的后端请求交易。
随后，且在交易类型需要时，Checkout SDK 会无缝管理额外的重定向操作，用于 3DS 验证或以其他方式验证付款。
要使用 SDK 有效管理交易重定向
- 在您的回调属性中，将
onCreatePayment属性定义为一个闭包。该闭包以paymentMethod和attemptReference作为输入，并返回已创建的卡对象。 - 在您的函数中
- 从您的服务器请求交易，随后从 Mangopay 请求交易。（您可以在请求中传入 attemptReference）
- 将未更改的交易响应对象返回给 SDK。
- SDK 会
- 在必要时将用户重定向到支付验证页面。
- 管理支付提供商重定向回 SDK。
- 使用交易的 ID 和状态触发
onPaymentComplete事件。 - 通过调用交易的相应 GET API 来确认服务器上的重定向结果。
- 向用户显示支付结果。
重定向示例
callback: CallBack(
onCreatePayment: { paymentMethod, attemptRef in
// 1. implement server-side call to request a transaction (with the attempt reference).
// 2. return the card transaction object.
return <Card_Transaction_Object>
}
)
Checkout Screen -> Payment sheet -> Confirmation screen
checkout = MGPPaymentSheet.create(
paymentMethodOptions: paymentConfig,
branding: PaymentFormStyle(),
callback: CallBack(
onTokenizationCompleted: { cardRegistration in
**//dismiss the payment sheet**
self.checkout.teardown()
**//present the confirmation screen**
},
onError: { error in
},
onSheetDismissed: {
}
)
)
checkout.present(in: self)
PaymentFormStyle 负责结账表单的样式设置和自定义
let branding = PaymentFormStyle(
font: .systemFont(ofSize: 12),
borderType: .round,
backgroundColor: .white,
textColor: .gray,
placeHolderColor: .darkGray,
borderColor: .black,
borderFocusedColor: .blue,
errorColor: .red,
checkoutButtonTextColor: .white,
checkoutButtonBackgroundColor: .black,
checkoutButtonDisabledBackgroundColor: .gray,
checkoutButtonText: "Checkout",
applePayButtonType: .plain,
applePayButtonStyle: .black,
applePayButtonCornerRadius: 8
)
....
checkout = MGPPaymentSheet.create(
client: mgpClient,
paymentMethodConfig: paymentConfig,
branding: branding,
callback: callback
)
| 属性 | 类型 | 描述 |
|---|---|---|
| 字体 | UIFont | 结账表单中文本字段和标签的字体 |
| 边框类型 | BorderType | 文本字段的边框类型。值为（方形 & 圆形） |
| 文本颜色 | UIColor | 结账表单中文本字段的文本颜色 |
| 占位符颜色 | UIColor | 结账表单中文本字段的文本字段占位符颜色。 |
| 边框颜色 | UIColor | 表单的边框颜色 |
| 聚焦边框颜色 | UIColor | 文本字段突出显示时的颜色。 |
| 错误颜色 | UIColor | 错误标签的颜色 |
| 结账按钮文本颜色 | UIColor | 结账按钮的颜色 |
| 结账按钮背景颜色 | UIColor | 结账按钮的背景颜色 |
| 结账按钮禁用背景颜色 | UIColor | 结账按钮的禁用颜色 |
| 结账按钮文本 | String (字符串) | 结账按钮文本 |
| 结账标题文本 | String (字符串) | 结账标题文本 |
| Apple Pay 按钮类型 | PKPaymentButtonType | Apple Pay 按钮类型 |
| Apple Pay 按钮样式 | PKPaymentButtonStyle | Apple Pay 按钮样式 |
| Apple Pay 按钮圆角半径 | CGFloat | Apple Pay 圆角半径 |