- 集成指南
- Mastercard Gateway Android SDK
Mastercard Gateway Android SDK
安装
此 SDK 打包为 maven 库。 应该解压缩到项目中的某个位置，并作为库添加到项目的 build.gradle 文件中。
- 从您的 Merchant Administration 门户下载 ZIP 文件格式的最新版本 SDK。
- 将此文件解压缩到 Android 项目的根目录。 （例如，~/my-android- project/gateway- repo）
- 在项目的
build.gradle文件中添加对此本地库的引用。 - 在您的应用模块的
build.gradle文件中，添加网关 SDK 作为依赖项。
有关下载 SDK 的更多信息，请参见 Mobile SDK 集成。
// build.gradle
allprojects {
repositories {
mavenCentral()
google()
// Gateway Android SDK repo
maven {
url "$rootDir/gateway-repo"
}
}
}
// 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
在使用 Android SDK 之前先对其初始化。 建议在 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",
"Your gateway region",
callback
)
}
会话概述
网关 SDK 流基于会话概念。 会话是参考会话的操作的所有请求字段和值的暂时容器。 有关详细信息，请参阅付款会话文档。
主要优点
- 您不处理或存储任何付款详细信息，因而降低了 PCI 合规成本。
- 由于不需要直接处理会话中存储的请求字段的值，因此使集成更轻松。
- 您的员工只能有限访问付款人的详细信息，因而减少了内部欺诈。
- 允许您更新会话中存储的请求字段和值。 当信用卡过期或其他付款人详细信息改变时，此功能非常有用。
- 允许您通过指定会话识别码来检索会话中包含的请求字段和值。
创建会话
创建与网关之间的会话，以在移动设备上发起付款流。
- 必须进行两次 API 调用来为移动交易准备此会话。
- 这些调用由 API 密码提供保护，因此需要从您的专用服务器调用。
| 请求参数 | 示例 |
|---|---|
| authenticationLimit | 25 |
更新会话
| 请求参数 | 存在 | 示例 |
|---|---|---|
| order.id | 必需 | your-order-id |
| order.amount | 必需 | 1.23 |
| order.currency | 必需 | AUD |
| authentication.acceptVersions | 必需 | 3DS2 |
| authentication.channel | 必需 | PAYER_APP |
| authentication.purpose | 必需 | PAYMENT_TRANSACTION |
在服务器上创建会话后，您应该
- 将会话信息返回到移动应用，并
- 创建
Session对象的实例。
// example
val session = Session(
id = "your-session-id",
amount = "1.23",
currency = "USD",
apiVersion = "61", // api version used to create the session
orderId = "your-order-id" // must match order id used on your server
)
收集卡信息
是否使用 updateSession 的 SDK 方法是可选的，但在帮助确定商家服务器 PCI 范围时，建议使用。 但是，卡和令牌信息可以通过不同的 API 设计加载，在 SDK 中调用以对付款人进行身份验证之前，这些信息必须出现在会话中。
手动输入卡信息
使用现有会话 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()
.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);
令牌化
SDK 提供使用卡信息更新会话的支持，您可以使用该会话对网关执行若干操作。 令牌化提供一种保留存档卡的方法，此功能可以在服务器上使用有效的会话执行。
按照以下步骤使用 Mobile SDK 来帮助创建卡令牌。
- 使用 SDK 创建和更新会话。
- 通过网关 SDK.
GatewayAPIupdateSession方法使用客户卡详细信息更新会话。 - 将会话 ID 返回到您的服务器，使用您的私人 API 凭据在网关上调用 Create or Update Token 方法。
- 令牌 ID 将返回，可以作为存档卡保留在服务器上。
有关令牌化的更多信息，请参阅 Create or Update Token 文档。
Google Pay
网关 SDK 附带一个名为 GooglePayHandler 的助手实用程序，用于从 Google Pay 电子钱包收集卡信息。
配置
要在应用中启用 Google Pay 支持，请参见 Google Pay 文档。
这些说明应会指导您如何：
- 设置 Google Pay API
- 从 Google 电子钱包请求付款信息
- 在布局中加入按钮，并
- 处理来自 Google Pay API 的响应。
由于 Google Pay 与网关 SDK 的集成是可选的，因此您必须提供适当的游戏服务依赖项。
implementation 'com.google.android.gms:play-services-wallet:X.X.X'
网关作为 PAYMENT_GATEWAY 类型与 Google Pay 集成。
从 Google Pay 请求加密卡信息
- 在您的请求中使用有效的名称
mpgs， - 将
YOUR_MERCHANT_ID替换为您在网关上使用的商家 ID。
val tokenizationSpecification = JSONObject()
.put("type", "PAYMENT_GATEWAY")
.put("parameters", JSONObject()
.put("gateway", "mpgs")
.put("gatewayMerchantId", "YOUR_MERCHANT_ID"))
请求电子钱包信息
使用 GooglePayHandler 在您构建的支付客户端上启动 Google Pay 电子钱包，然后请求数据。
// YourActivity.kt
fun googlePayButtonClicked()
{ try {
val request = PaymentDataRequest.fromJson(paymentDataRequest.toString())
// use the Gateway convenience handler for launching the Google Pay flow
GooglePayHandler.requestData(this, paymentsClient, request)
} catch (e: JSONException) {
Toast.makeText(this, "Could not request payment data", Toast.LENGTH_SHORT).show()
}
}
处理电子钱包响应
网关 SDK 为方便用户使用提供了一个 Google Pay 生命周期处理程序。 您可以实现提供的 Google Pay 回调，在活动中使用结果处理程序。
这免除了手动处理 Google Pay 活动结果的需要，将重要的交易步骤委托给回调方法。
// YourActivity.kt
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?)
{
// handle the Google Pay response
if (GooglePayHandler.handleActivityResult(requestCode, resultCode, data, callback)) {
return
}
super.onActivityResult(requestCode, resultCode, data)
}
val googlePayCallback = object : GooglePayCallback {
override fun onReceivedPaymentData(paymentData: JSONObject) {
try {
val description = paymentData.getJSONObject("paymentMethodData")
.getString("description")
Log.d(MyGooglePayCallback::class.java.simpleName,"ReceivedPaymentData: $description")
} catch (e: Exception) {
// handle exception
}
handleGooglePayData(paymentData)
}
override fun onGooglePayCancelled() {
// handle cancelled
}
override fun onGooglePayError(status: Status) {
// handle error
}
}
使用付款令牌更新会话
请在您从 Google Pay 收到付款数据后立即更新与网关之间的会话。
fun handleGooglePayData(paymentData: JSONObject) {
val token = paymentData.getJSONObject("paymentMethodData")
.getJSONObject("tokenizationData")
.getString("token")
val request = GatewayMap()
.set("sourceOfFunds.provided.card.devicePayment.paymentToken", token)
GatewayAPI.updateSession(session, request, callback)
}
付款人身份验证
3D 验证
3D 验证或 3DS 身份验证允许您在提交 Authorization 或 Pay 交易前对付款人进行身份验证，从而保护在线购买、防范信用卡欺诈。
EMV 3DS 是新版本，在网关中也称为 3DS2，旨在增强在线购物的安全性，同时为访问控制服务器 (ACS) 认为低风险的付款人提供无障碍结账服务。
ACS 可以使用商家提供的信息、设备指纹识别或与付款人的先前交互，或者将其中二者同时使用来确定风险。 仅当需要进行额外验证来对付款人进行身份验证时，ACS 才会对付款人进行质询（例如，输入 PIN），从而提高转化率。
支持的身份验证计划包括 Mastercard Identity Check、Visa Secure 和 American Express SafeKey。
Mobile SDK 中的身份验证仅限于 3DS2。 如果 3DS2 不可用，身份验证将不会继续。 但是，如果网关建议您继续处理付款，您仍然可以继续。
有关 3DS 支付验证的更多信息，请参阅 3DS 支付验证文档。
身份验证详细信息
当您执行 Mobile SDK 身份验证（即在移动应用中验证持卡人的身份）时，嵌入的 Mobile SDK 会收集设备指标，并将其与交易信息一起发送到网关。
请尽可能多地提供有关付款人和交易的信息，以提高身份验证成功的可能性。
这些信息可以通过 Update session 请求添加到您的 session 中。
| 参数 | 存在 | 说明 |
|---|---|---|
| order.merchantCategoryCode | 可选 | 与商家配置文件中的代码相同 |
| billing.address 参数组 | 可选 | 只要可能，强烈建议您将此参数组包含在请求中 |
| shipping.address 参数组 | 可选 | 只要可能，强烈建议您将此参数组包含在请求中 |
| customer 参数组 | 可选 | 只要可能，强烈建议您将此参数组包含在请求中 |
device 参数组仅与基于浏览器的付款有关。 不应用于基于移动应用的付款人身份验证。这些指标帮助系统确定如何或是否对持卡人进行身份验证。 在身份验证过程中，用户可能会经历以下两个身份验证流中的一个：
- 无障碍： ACS 已经收集了足够的持卡人信息来对他们进行身份验证。 用户无需执行其他操作。
- 质询： ACS 要求持卡人完成额外的身份验证步骤，即输入一次性密码、登录发卡银行等。 嵌入的 Mobile SDK 对为此质询显示本地设备界面的过程进行处理。 这些屏幕的 UI 可以通过在初始化期间将
UICustomization参数传送到网关 SDK 来自定义。
有关详细信息，请参见 Authenticate Payer 文档。
authentication.PSD2.exemption 的参数组。 执行身份验证
付款人身份验证在网关中被视为一项特有交易，因此需要一个唯一的交易 ID。
如果您在收取订单的付款，您可以
- 通过对每个交易使用相同的订单 ID 来关联付款和身份验证交易。
- 每个交易在网关的 Web 门户中显示为单独的交易，如 UUID。
AuthenticationHandler.authenticate(activityContext, session, "your-auth- transaction-id", callback)
your-auth-transaction-id 是此交易的唯一标识符，用于将其与订单上的任何其他交易进行区分。 需要提供此信息，是因为当您要求 SDK 对付款人进行身份验证时，网关将使用 your-auth-transaction-id 查找其存储的身份验证结果。 然后，网关将支付请求所需的信息传送到收单行。解释响应
authenticate 方法将返回一个 AuthenticationResponse 对象，其中包含：
- 有关结果的重要信息，以及
- 操作期间执行的操作。
要使用的最重要的字段是 response.recommendation。 字段中可能包含值 PROCEED 或 DO_NOT_PROCEED。
- PROCEED： 指示“可以继续付款或授权”。
- DO_NOT_PROCEED： 指示身份验证操作期间出现问题。
AuthenticationError对象可以用来确定更多情况。
在 Gateway API 版本 70 及更高版本中，您可能会收到以下错误：
AuthenticationError.recommendation_ResubmitWithAlternativePaymentDetails: 指示您应该向付款人询问备用付款详细信息。 例如，新卡或其他付款方式，然后使用新详细信息重新提交请求。AuthenticationError.recommendation_AbandonOrder: 指示支付服务提供商、组织或发卡机构要求您放弃订单。AuthenticationError.recommendation_DoNotProceed: 指示网关的请求失败，此交易无法成功完成。
有关更多信息，请参见集成指南。
AuthenticationHandler.authenticate(activityContext, session, "your-auth-transaction-id") { response ->
when(response.recommendation) {
AuthenticationRecommendation.PROCEED -> {
// continue to payment/authorization
}
AuthenticationRecommendation.DO_NOT_PROCEED -> {
if (response.error !=null) {
if (response.error is AuthenticationError.RecommendationResubmitWithAlternativePaymentDetails) {
// "Authentication not successful, re-enter card details
}
} else {
// "Authentication not successful"
}
}
}
}
如果身份验证失败，您可以检查 response.error，进一了解导致失败的原因。