此页面由 Cloud Translation API 翻译。

Android 付款应用开发者指南

了解如何调整您的 Android 付款应用，使其支持网络付款，并为客户提供更好的用户体验。

Eiji Kitamura

Yuichi Araki

Payment Request API 面向 Web 引入了基于浏览器的内置界面，可让用户比以往更轻松地输入所需的付款信息。API 还可以调用平台专用的付款应用。

浏览器支持

60
15
11.1

来源

针对具体平台且使用 Web Payments 的 Google Pay 应用的结账流程。

与仅使用 Android intent 相比，Web Payments 可以更好地与浏览器集成，并提高安全性和用户体验：

付款应用作为模态在商家网站环境中启动。
实现是对现有付款应用的补充，使您能够充分利用用户群。
系统会检查付款应用的签名，以防止发生旁加载。
付款应用可以支持多种付款方式。
您可以集成任何付款方式，例如加密货币、银行转账等。Android 设备上的付款应用甚至可以集成需要访问设备硬件芯片的方法。

在 Android 付款应用中实现 Web Payments 需要执行四个步骤：

让商家发现您的付款应用。
告知商家客户是否已经注册付款方式（例如信用卡）。
让客户付款。
验证调用方的签名证书。

如需了解网络付款的实际应用，请查看 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`

不带 scheme 的商家来源（顶级浏览上下文的无协议来源）。例如，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()

如果从调用的付款应用收到的付款响应的 activity 结果设置为 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) } }

Android 付款应用开发者指南

第 1 步：让商家发现您的付款应用

第 2 步：告知商家客户是否有可以付款的已注册付款方式

AndroidManifest.xml

AIDL

实施 IsReadyToPayService

响应

权限

第 3 步：让客户付款

AndroidManifest.xml

参数

methodNames

methodData

merchantName

topLevelOrigin

topLevelCertificateChain

paymentRequestOrigin

total

modifiers

paymentRequestId

响应

权限

第 4 步：验证调用方的签名证书

`AndroidManifest.xml`

实施 `IsReadyToPayService`

`AndroidManifest.xml`

`methodData`

`topLevelOrigin`

`topLevelCertificateChain`

`paymentRequestOrigin`

`total`

`modifiers`

`paymentRequestId`