集成步骤
要将 iOS 或 Android Mobile SDK 与 Mastercard Gateway 结合使用，请按照以下说明操作。
步骤 1： 下载 SDK 和文档
iOS 和 Android Mobile SDK 及相关文档可从 Merchant Administration (MA) 下载：
- 登录 MA，然后选择“管理 > 软件下载”。
- 选择适当的链接并按照提示下载所需文件。
如果您在“管理”菜单中看不到“软件下载”，请要求 your payment service provider 提供 Mobile SDK 访问权限。
管理 - 软件和文档下载屏幕将显示。 它包含 Mobile SDK 和 Mobile SDK 集成指南。
适用于 iOS 的设备和模拟器版本
iOS 版 Mobile SDK 发布了两个版本：
- 设备版本： 设备版本已启用位码，让应用在用户设备上占用的空间更小。 但是此版本不支持 x86_64 体系结构。 开发人员倾向于将 SDK 的设备版本作为发布版本。
- 模拟器版本： 要使用模拟器，您需要 x86_64 体系结构。 这意味着位码被禁用，应用会占用更大的空间。 在开发过程中，开发人员倾向于使用模拟器版本，因为此时占用空间并不是一个真正的问题。
网关发布了启用位码的设备和禁用位码的模拟器两个版本的 SDK，在任何给定场景中，您都可以选择要使用的内容。 两个版本的功能和界面完全相同。
有关更多信息，请参阅 Apple 的文档：
步骤 2： 安装并初始化 SDK
此部分包括有关如何安装和初始化 SDK 的说明。
iOS
要将 SDK 安装到您的 Xcode 项目中：
- 将
Gateway-SDK.xcframework文件夹拖到您的 Xcode 项目中。 - 将库添加到目标的“框架、库和嵌入内容”中。
- 在需要时对框架执行 import Gateway。
- 如果需要，使用 .binaryTarget 选项将 Gateway-SDK.xcframework 设置为本地 swift 包。
- 确保在您的项目中包含 uSDK.xcframework。 SDK 依赖于 ZIP 文件中捆绑的 uSDK.xcframework。
// AppDelegate.swift import Gateway
使用 SDK 之前必须先初始化 SDK。 建议在 AppDelegate 类中执行此操作。
请联系 您的支付服务提供商 了解您的网关地区。
// AppDelegate.swift
GatewaySDK.shared.initialize(
merchantId: "MERCHANT_ID",
merchantName: "Merchant Name",
merchantUrl: "https://merchant-url.com",
region: "Your gateway region"
Android
SDK 被打包为 maven 存储库。
要将 SDK 安装到您的项目中：
- 将文件解压缩到您的 Android 项目的根目录中，例如，~/my-android- project/gateway-repo)。
- 在项目的
build.gradle文件中添加对此本地存储库的引用。 - 在您的应用模块的
build.gradle文件中，将 Mobile SDK 作为依赖项包含在内。
// build.gradle
allprojects {
repositories {
mavenCentral()
google()
// Gateway Android SDK repo
maven {
url "$rootDir/gateway-repo"
}
}
}
将 X.X.X 替换为当前版本号。
// app/build.gradle implementation 'com.mastercard.gateway:Mobile_SDK_Android:x.x.x'
Mobile_SDK_Android 文件夹包含一个 maven-metadata.xml 文件，该文件包含构建库的实现参考的信息。 实现 gradle 的格式为 implementation <groupId>:<artifactId>:<version>。
使用 SDK 之前必须先初始化 SDK。 建议在您的自定义 Application 类中在 onCreate() 函数中执行此操作。
请联系 您的支付服务提供商 了解您的网关地区。
// CustomApplication.kt
override fun onCreate()
{
super.onCreate()
// init Gateway SDK
GatewaySDK.initialize
(
this,
"YOUR_MERCHANT_ID",
"Your Merchant Name",
"https://your-merchant-url.com",
region: "Your gateway region",
callback
)
}
集成我们 SDK 的安全建议
- 更新会话尝试限制： 实施会话更新尝试限制，以防止暴力攻击和未经授权的访问。
- 其他安全措施：
- CAPTCHA 集成： 使用 CAPTCHA 验证用户真实性并防止自动攻击。
- 生物特征认证： 采用指纹或面部识别进行强大的用户身份验证并阻止未经授权的访问尝试。
- DDoS 防护： 实施强大的 DDoS 防护机制，防范大体量攻击，确保持续的服务可用性。
- 机器人检测： 采用先进的技术来识别和减轻利用应用程序漏洞的恶意机器人活动。
- 速率限制： 实施严格的速率限制策略来规范来自客户端或 IP 地址的请求，确保公平的资源分配并减少滥用。
- 使用我们自己的服务器进行 SSL 固定： 包括 SSL 固定，以确保安全通信，阻止中间人攻击和未经授权的服务器访问。
步骤 3： 创建和更新会话
Mobile SDK 流基于会话概念。 会话是参考会话的操作的所有请求字段和值的暂时容器。 有关详细信息，请参阅会话基础知识。
创建并更新与网关之间的会话，以在移动设备上发起付款流：
- 要准备此会话以进行移动交易，发送
CREATE SESSIONAPI 请求。 对于请求字段，请参阅CREATE SESSION请求字段表。 - 要更新会话，发送包含必需字段的
UPDATE SESSION请求。 对于请求字段，请参阅必需的UPDATE SESSION请求字段表。
由于会话请求由 API 密码保护，因此应从您的服务器发送会话，而不是从移动应用发送。
表： CREATE SESSION 请求字段
| 请求参数 | 说明 | 示例 |
|---|---|---|
| authenticationLimit | 使用此会话的 ID 作为密码可以提交给网关的操作数。 会话 ID 在与 3DS 支付验证 (3DS) 相关的经过会话身份验证的请求中用作密码。 | 25 |
表： 必需的 UPDATE SESSION 请求字段
| 请求参数 | 说明 | 示例 |
|---|---|---|
| order.id | 此订单的唯一标识符。 | your-order-id |
| order.amount | 订单总金额。 | 1.23 |
| order.currency | 订单的货币。 | AUD |
| authentication.acceptVersions | 您接受用于此付款的 3DS 版本。 如果您未指定版本，则接受 3DS2。 网关将使用 3DS2（如果发卡机构和卡支持）。 如果 3DS2 不可用，则身份验证无法继续。 | 3DS2 |
| authentication.channel | 发起身份验证请求的通道。 | PAYER_APP |
| authentication.purpose | 身份验证的目的。 | PAYMENT_TRANSACTION |
要在 SDK 中对付款人进行身份验证，必须发出 CREATE SESSION 和 UPDATE SESSION 请求，并更新会话中的付款详细信息。 API 设计决定了如何以及何时将付款详细信息加载到会话中。
在您的服务器上创建会话后：
- 将会话信息返回到移动应用以在其他操作中使用。
- 创建
Session对象的实例。
let sessionId = "session-id" let apiVersion = "61" // api version used to create the session let orderId = "order-id" // must match order id used on your server let amount = "1.23" let currency = "USD"
// example
val session = Session(
id = "session-id",
amount = "1.23",
currency = "USD",
apiVersion = "61", // api version used to create the session
orderId = "order-id" // must match order id used on your server
)
从会话创建到最终付款，整个交易生命周期的
apiVersion 必须相同。步骤 4： 收集付款信息
您可以 通过多种方式向付款人收集付款信息：
- 如果您的 PCI 合规级别允许，您可以手动收集卡详细信息并将其添加到会话中。 有关更多信息，请参阅人工卡详细信息。
- 如果您的 PCI 合规级别不允许您处理敏感数据，您可以使用 Apple Pay 或 Google Pay 付款方式获取代表付款人已添加到其 Apple 或 Google Pay 电子钱包的卡的付款令牌。 然后将令牌添加到会话中。 如需了解更多信息，请参阅 Apple Pay 和 Google Pay。
updateSession() 函数用于在 Mobile SDK 中将付款信息、卡详细信息或令牌添加到会话中。 在您进行可选的付款人身份验证和实际付款交易之前，付款信息必须存在于会话中。
updateSession() 函数是在不影响 PCI 范围的情况下将付款详细信息上传到会话的最简单方法。 但是，如果不需要考虑 PCI 范围，您也可以通过其他方式上传详细信息，如通过从您的服务器发起 UPDATE SESSION 请求。人工卡详细信息
在应用屏幕上向付款人收集卡详细信息，并使用之前 CREATE SESSION 响应中返回的会话 ID 将信息直接传递到网关。
// The GatewayMap object provides support for building a nested map structure using key-based dot(.) notation.
// Each parameter is similarly defined in your online integration guide.
val request = GatewayMap()
request.sourceOfFunds.provided.card.nameOnCard.value = nameOnCard
request.sourceOfFunds.provided.card.number.value = cardNumber
request.sourceOfFunds.provided.card.securityCode.value = cvv
request.sourceOfFunds.provided.card.expiry.month.value = cardExpiryMM
request.sourceOfFunds.provided.card.expiry.year.value = cardExpiryYY
GatewayAPI.shared.updateSession(sessionId, apiVersion: apiVersion, payload: request) { (response) in
// handle result
}
// The GatewayMap object provides support for building a nested map structure using key-based dot(.) notation.
// Each parameter is similarly defined in your online integration guide.
val request = GatewayMap()
.set("sourceOfFunds.provided.card.nameOnCard", nameOnCard)
.set("sourceOfFunds.provided.card.number", cardNumber)
.set("sourceOfFunds.provided.card.securityCode", cardCvv)
.set("sourceOfFunds.provided.card.expiry.month", cardExpiryMM)
.set("sourceOfFunds.provided.card.expiry.year", cardExpiryYY);
GatewayAPI.updateSession(session, request, callback);
使用卡详细信息更新会话后，您可以将卡详细信息令牌化，这样，您可以存储令牌以供将来在付款人返回或您需要执行商家发起交易时使用。 例如，由于定期付款。 要将卡详细信息令牌化，使用您的服务器中的 CREATE Or UPDATE TOKEN 操作以及有效的会话 ID。 有关更多信息，请参见令牌化。
步骤 5： 创建付款交易
当付款人已经通过身份验证且会话包含付款详细信息（例如卡详细信息或令牌）时，从您的服务器发送 PAY 或 AUTHORIZE 付款交易请求，并在请求中包含会话 ID。 有关更多信息，请参见“发起服务器 API 请求”。