了解如何调整您的 Android 付款应用,使其与 Web Payments 搭配使用,并为客户提供更好的体验。
Payment Request API 为网页提供了一个基于浏览器的内置界面,使用户可以比以往更轻松地输入所需的付款信息。此 API 还可以调用平台特定的付款应用。
与仅使用 Android intent 相比,网络付款支持更好的与浏览器集成、安全性和用户体验:
- 在商家网站的上下文中,付款应用以模态形式启动。
- 实现是对现有付款应用的补充,可让您充分利用用户群。
- 系统会检查付款应用的签名,以防止旁加载。
- 付款应用可支持多种付款方式。
- 任何付款方式(例如加密货币、银行转账等)都可以集成。Android 设备上的付款应用甚至可以集成需要访问设备上的硬件芯片的方法。
在 Android 付款应用中实现网络付款需要完成四个步骤:
- 让商家发现您的付款应用。
- 告知商家客户是否有已注册的付款方式(例如信用卡)已准备好进行付款。
- 让客户付款。
- 验证调用方的签名证书。
如需了解网络付款的实际应用,请观看 android-web-payment 演示。
第 1 步:让商家发现您的付款应用
商家需要使用 Payment Request API 并通过付款方式标识符指定您支持的付款方式,商家才能使用您的付款应用。
如果您的付款应用有专属的付款方式标识符,您可以设置自己的付款方式清单,以便浏览器可以发现您的应用。
第 2 步:告知商家客户是否已有可供付款的已注册付款方式
商家可以调用 hasEnrolledInstrument()
来查询客户是否能够付款。您可以将 IS_READY_TO_PAY
作为 Android 服务来实现来回答此查询。
AndroidManifest.xml
使用具有 org.chromium.intent.action.IS_READY_TO_PAY
操作的 intent 过滤器声明您的服务。
<service
android:name=".SampleIsReadyToPayService"
android:exported="true">
<intent-filter>
<action android:name="org.chromium.intent.action.IS_READY_TO_PAY" />
</intent-filter>
</service>
IS_READY_TO_PAY
服务是可选的。如果付款应用中没有此类 intent 处理程序,则网络浏览器会假定该应用始终可以进行付款。
AIDL
IS_READY_TO_PAY
服务的 API 是在 AIDL 中定义的。创建两个包含以下内容的 AIDL 文件:
app/src/main/aidl/org/chromium/IsReadyToPayServiceCallback.aidl
package org.chromium;
interface IsReadyToPayServiceCallback {
oneway void handleIsReadyToPay(boolean isReadyToPay);
}
app/src/main/aidl/org/chromium/IsReadyToPayService.aidl
package org.chromium;
import org.chromium.IsReadyToPayServiceCallback;
interface IsReadyToPayService {
oneway void isReadyToPay(IsReadyToPayServiceCallback callback);
}
实施 IsReadyToPayService
IsReadyToPayService
的最简单实现如下例所示:
class SampleIsReadyToPayService : Service() {
private val binder = object : IsReadyToPayService.Stub() {
override fun isReadyToPay(callback: IsReadyToPayServiceCallback?) {
callback?.handleIsReadyToPay(true)
}
}
override fun onBind(intent: Intent?): IBinder? {
return binder
}
}
响应
服务可通过 handleIsReadyToPay(Boolean)
方法发送其响应。
callback?.handleIsReadyToPay(true)
权限
您可以使用 Binder.getCallingUid()
检查调用方是谁。请注意,您必须在 isReadyToPay
方法而不是 onBind
方法中执行此操作。
override fun isReadyToPay(callback: IsReadyToPayServiceCallback?) {
try {
val callingPackage = packageManager.getNameForUid(Binder.getCallingUid())
// …
如需了解如何验证发起调用的软件包是否具有正确的签名,请参阅验证调用方的签名证书。
第 3 步:让客户付款
商家调用 show()
以启动付款应用,以便客户进行付款。付款应用是通过 Android intent PAY
(intent 参数中包含交易信息)调用的。
付款应用会返回 methodName
和 details
,它们是付款应用专有的,对浏览器是不透明的。浏览器通过 JSON 反序列化将 details
字符串转换为商家的 JavaScript 对象,但不强制执行任何有效性。浏览器不会修改 details
;该参数的值会直接传递给商家。
AndroidManifest.xml
具有 PAY
intent 过滤器的 activity 应该有一个 <meta-data>
标记,用于标识应用的默认付款方式标识符。
如需支持多种付款方式,请添加带有 <string-array>
资源的 <meta-data>
标记。
<activity
android:name=".PaymentActivity"
android:theme="@style/Theme.SamplePay.Dialog">
<intent-filter>
<action android:name="org.chromium.intent.action.PAY" />
</intent-filter>
<meta-data
android:name="org.chromium.default_payment_method_name"
android:value="https://bobbucks.dev/pay" />
<meta-data
android:name="org.chromium.payment_method_names"
android:resource="@array/method_names" />
</activity>
resource
必须是一个字符串列表,其中每个字符串都必须是采用 HTTPS 架构的有效绝对网址,如下所示。
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string-array name="method_names">
<item>https://alicepay.com/put/optional/path/here</item>
<item>https://charliepay.com/put/optional/path/here</item>
</string-array>
</resources>
参数
以下参数会作为 intent extra 传递给 activity:
methodNames
methodData
topLevelOrigin
topLevelCertificateChain
paymentRequestOrigin
total
modifiers
paymentRequestId
val extras: Bundle? = intent?.extras
methodNames
所用方法的名称。这些元素是 methodData
字典中的键。以下是该付款应用支持的方法。
val methodNames: List<String>? = extras.getStringArrayList("methodNames")
methodData
从每个 methodNames
到 methodData
的映射。
val methodData: Bundle? = extras.getBundle("methodData")
merchantName
商家结账页(浏览器的顶级浏览上下文)的 <title>
HTML 标记的内容。
val merchantName: String? = extras.getString("merchantName")
topLevelOrigin
不带协议方案的商家来源(顶级浏览上下文的无协议来源)。例如,https://mystore.com/checkout
会作为 mystore.com
进行传递。
val topLevelOrigin: String? = extras.getString("topLevelOrigin")
topLevelCertificateChain
商家的证书链(顶级浏览上下文的证书链)。对于 localhost 和磁盘上的文件,则为 null,它们都是没有 SSL 证书的安全上下文。每个 Parcelable
都是具有 certificate
键和字节数组值的 Bundle。
val topLevelCertificateChain: Array<Parcelable>? =
extras.getParcelableArray("topLevelCertificateChain")
val list: List<ByteArray>? = topLevelCertificateChain?.mapNotNull { p ->
(p as Bundle).getByteArray("certificate")
}
paymentRequestOrigin
调用 JavaScript 中的 new
PaymentRequest(methodData, details, options)
构造函数的 iframe 浏览上下文的无传输协议来源。如果构造函数是从顶级上下文调用的,则此参数的值等于 topLevelOrigin
参数的值。
val paymentRequestOrigin: String? = extras.getString("paymentRequestOrigin")
total
表示交易总金额的 JSON 字符串。
val total: String? = extras.getString("total")
下面是该字符串的内容示例:
{"currency":"USD","value":"25.00"}
modifiers
JSON.stringify(details.modifiers)
的输出,其中 details.modifiers
仅包含 supportedMethods
和 total
。
paymentRequestId
“推送付款”应用应与交易状态相关联的 PaymentRequest.id
字段。商家网站将使用此字段查询“推送付款”应用,以了解带外交易的状态。
val paymentRequestId: String? = extras.getString("paymentRequestId")
响应
activity 可以使用 RESULT_OK
通过 setResult
发回其响应。
setResult(Activity.RESULT_OK, Intent().apply {
putExtra("methodName", "https://bobbucks.dev/pay")
putExtra("details", "{\"token\": \"put-some-data-here\"}")
})
finish()
您必须指定两个参数作为 intent extra:
methodName
:所用方法的名称。details
:包含商家完成交易所需的信息的 JSON 字符串。如果成功为true
,则构建details
的方式必须确保JSON.parse(details)
会成功。
如果交易未在付款应用中完成(例如,如果用户未能在付款应用中为其账号输入正确的 PIN 码),您可以传递 RESULT_CANCELED
。浏览器可能会允许用户选择其他付款应用。
setResult(RESULT_CANCELED)
finish()
如果从调用的付款应用收到的付款响应的活动结果设置为 RESULT_OK
,Chrome 将在其 extra 中检查是否存在非空的 methodName
和 details
。如果验证失败,Chrome 将从 request.show()
返回被拒绝的 promise,以及以下向开发者显示的错误消息之一:
'Payment app returned invalid response. Missing field "details".'
'Payment app returned invalid response. Missing field "methodName".'
权限
activity 可以使用其 getCallingPackage()
方法检查调用方。
val caller: String? = callingPackage
最后一步是验证调用方的签名证书,以确认调用软件包是否具有正确的签名。
第 4 步:验证调用方的签名证书
您可以使用 IS_READY_TO_PAY
中的 Binder.getCallingUid()
以及 PAY
中的 Activity.getCallingPackage()
检查调用方的软件包名称。为了实际验证调用方是否是您想要使用的浏览器,您应检查其签名证书,并确保它与正确的值匹配。
如果您的目标 API 级别为 28 及更高级别,并且要与只有一个签名证书的浏览器集成,则可以使用 PackageManager.hasSigningCertificate()
。
val packageName: String = … // The caller's package name
val certificate: ByteArray = … // The correct signing certificate.
val verified = packageManager.hasSigningCertificate(
callingPackage,
certificate,
PackageManager.CERT_INPUT_SHA256
)
单证书浏览器首选 PackageManager.hasSigningCertificate()
,因为它可以正确处理证书轮替。(Chrome 只有一个签名证书。)具有多个签名证书的应用无法轮替这些证书。
如果您需要支持旧版 API 级别 27 及更低级别,或者需要处理具有多个签名证书的浏览器,您可以使用 PackageManager.GET_SIGNATURES
。
val packageName: String = … // The caller's package name
val certificates: Set<ByteArray> = … // The correct set of signing certificates
val packageInfo = getPackageInfo(packageName, PackageManager.GET_SIGNATURES)
val sha256 = MessageDigest.getInstance("SHA-256")
val signatures = packageInfo.signatures.map { sha256.digest(it.toByteArray()) }
val verified = signatures.size == certificates.size &&
signatures.all { s -> certificates.any { it.contentEquals(s) } }