此页面由 Cloud Translation API 翻译。

Android 付款应用开发者指南
bookmark_border 使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。

了解如何调整您的 Android 付款应用以支持 Web Payments，并为客户提供更好的用户体验。

Eiji Kitamura

Yuichi Araki

发布时间：2020 年 5 月 5 日；最后更新时间：2025 年 5 月 27 日

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

Browser Support

Source

使用 Web Payments 的平台专用 Google Pay 应用的结账流程。

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

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

在 Android 付款应用中实现 Web Payments 需要完成以下四个步骤：

让商家发现您的付款应用。
告知商家客户是否有已注册的付款工具（例如信用卡）可供付款。
允许客户付款。
验证调用方的签名证书。

如需了解 Web Payments 的实际运作方式，请查看 android-web-payment 演示。

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

按照设置付款方式中的说明在 Web 应用清单中设置 related_applications 属性。

商家若要使用您的付款应用，则需要使用 PaymentRequest 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 文件：

org/chromium/IsReadyToPayServiceCallback.aidl

package org.chromium;

interface IsReadyToPayServiceCallback {
    oneway void handleIsReadyToPay(boolean isReadyToPay);
}

org/chromium/IsReadyToPayService.aidl

package org.chromium;

import org.chromium.IsReadyToPayServiceCallback;

interface IsReadyToPayService {
    oneway void isReadyToPay(IsReadyToPayServiceCallback callback, in Bundle parameters);
}

实施 `IsReadyToPayService`

以下示例展示了 IsReadyToPayService 的最简单实现：

KotlinJava

class SampleIsReadyToPayService : Service() {
    private val binder = object : IsReadyToPayService.Stub() {
        override fun isReadyToPay(callback: IsReadyToPayServiceCallback?, parameters: Bundle?) {
            callback?.handleIsReadyToPay(true)
        }
    }

    override fun onBind(intent: Intent?): IBinder? {
        return binder
    }
}

import org.chromium.IsReadyToPayService;

public class SampleIsReadyToPayService extends Service {
    private final IsReadyToPayService.Stub mBinder =
        new IsReadyToPayService.Stub() {
            @Override
            public void isReadyToPay(IsReadyToPayServiceCallback callback, Bundle parameters) {
                if (callback != null) {
                    callback.handleIsReadyToPay(true);
                }
            }
        };

    @Override
    public IBinder onBind(Intent intent) {
        return mBinder;
    }
}

响应

服务可以使用 handleIsReadyToPay(Boolean) 方法发送响应。

KotlinJava

callback?.handleIsReadyToPay(true)

if (callback != null) {
    callback.handleIsReadyToPay(true);
}

权限

您可以使用 Binder.getCallingUid() 检查调用方是谁。请注意，您必须在 isReadyToPay 方法（而非 onBind 方法）中执行此操作，因为 Android OS 可以缓存和重复使用服务连接，而这不会触发 onBind() 方法。

KotlinJava

override fun isReadyToPay(callback: IsReadyToPayServiceCallback?, parameters: Bundle?) {
    try {
        val untrustedPackageName = parameters?.getString("packageName")
        val actualPackageNames = packageManager.getPackagesForUid(Binder.getCallingUid())
        // ...

@Override
public void isReadyToPay(IsReadyToPayServiceCallback callback, Bundle parameters) {
    try {
        String untrustedPackageName = parameters != null
                ? parameters.getString("packageName")
                : null;
        String[] actualPackageNames = packageManager.getPackagesForUid(Binder.getCallingUid());
        // ...

收到进程间通信 (IPC) 调用时，请始终检查 null 的输入参数。这一点尤为重要，因为 Android OS 的不同版本或分支可能会以意外的方式运行，如果不加以处理，可能会导致错误。

虽然 packageManager.getPackagesForUid() 通常会返回单个元素，但您的代码必须处理调用方使用多个软件包名称的不常情况。这可确保您的应用保持稳健。

如需了解如何验证调用软件包是否具有正确的签名，请参阅验证调用方的签名证书。

参数

Chrome 139 中添加了 parameters 软件包。应始终与 null 进行对比检查。

以下参数会传递给 parameters 软件包中的服务：

packageName
methodNames
methodData
topLevelOrigin
paymentRequestOrigin
topLevelCertificateChain

packageName 已在 Chrome 138 中添加。您必须先根据 Binder.getCallingUid() 验证此参数，然后才能使用其值。此验证至关重要，因为 parameters 软件包由调用方完全控制，而 Binder.getCallingUid() 由 Android OS 控制。

在 WebView 中，以及通常用于本地测试的非 https 网站（例如 http://localhost）上，topLevelCertificateChain 为 null。

第 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/chromium_payment_method_names" />
</activity>

android:resource 必须是字符串列表，其中每个字符串都必须是采用 HTTPS 协议方案的有效绝对网址，如下所示。

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="chromium_payment_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
merchantName
topLevelOrigin
topLevelCertificateChain
paymentRequestOrigin
total
modifiers
paymentRequestId
paymentOptions
shippingOptions

KotlinJava

val extras: Bundle? = getIntent()?.extras

Bundle extras = getIntent() != null ? getIntent().getExtras() : null;

methodNames

所使用的方法的名称。这些元素是 methodData 字典中的键。这些是付款应用支持的方法。

KotlinJava

val methodNames: List<String>? = extras.getStringArrayList("methodNames")

List<String> methodNames = extras.getStringArrayList("methodNames");

`methodData`

将每个 methodNames 映射到 methodData。

KotlinJava

val methodData: Bundle? = extras.getBundle("methodData")

Bundle methodData = extras.getBundle("methodData");

`merchantName`

商家结账页（浏览器的顶级浏览上下文）的 <title> HTML 标记的内容。

KotlinJava

val merchantName: String? = extras.getString("merchantName")

String merchantName = extras.getString("merchantName");

`topLevelOrigin`

不带 scheme 的商家来源（顶级浏览上下文的无 scheme 来源）。例如，https://mystore.com/checkout 会作为 mystore.com 传递。

KotlinJava

val topLevelOrigin: String? = extras.getString("topLevelOrigin")

String topLevelOrigin = extras.getString("topLevelOrigin");

`topLevelCertificateChain`

商家的证书链（顶级浏览上下文的证书链）。对于 WebView、localhost 或磁盘上的文件，该值为 null。每个 Parcelable 都是一个包含 certificate 键和字节数组值的 Bundle。

KotlinJava

val topLevelCertificateChain: Array<Parcelable>? =
        extras.getParcelableArray("topLevelCertificateChain")
val list: List<ByteArray>? = topLevelCertificateChain?.mapNotNull { p ->
    (p as Bundle).getByteArray("certificate")
}

Parcelable[] topLevelCertificateChain =
        extras.getParcelableArray("topLevelCertificateChain");
if (topLevelCertificateChain != null) {
    for (Parcelable p : topLevelCertificateChain) {
        if (p != null && p instanceof Bundle) {
            ((Bundle) p).getByteArray("certificate");
        }
    }
}

`paymentRequestOrigin`

调用了 JavaScript 中的 new PaymentRequest(methodData, details, options) 构造函数的 iframe 浏览上下文的无架构来源。如果从顶级上下文调用了构造函数，则此参数的值等于 topLevelOrigin 参数的值。

KotlinJava

val paymentRequestOrigin: String? = extras.getString("paymentRequestOrigin")

String paymentRequestOrigin = extras.getString("paymentRequestOrigin");

`total`

表示交易总金额的 JSON 字符串。

KotlinJava

val total: String? = extras.getString("total")

String total = extras.getString("total");

下面是字符串的内容示例：

{"currency":"USD","value":"25.00"}

`modifiers`

JSON.stringify(details.modifiers) 的输出，其中 details.modifiers 仅包含 supportedMethods、data 和 total。

`paymentRequestId`

“推送付款”应用应与交易状态关联的 PaymentRequest.id 字段。商家网站将使用此字段来查询“推送付款”应用，以便在非正规渠道中了解交易状态。

KotlinJava

val paymentRequestId: String? = extras.getString("paymentRequestId")

String paymentRequestId = extras.getString("paymentRequestId");

响应

activity 可以使用 RESULT_OK 通过 setResult 发回其响应。

KotlinJava

setResult(Activity.RESULT_OK, Intent().apply {
    putExtra("methodName", "https://bobbucks.dev/pay")
    putExtra("details", "{\"token\": \"put-some-data-here\"}")
})
finish()

Intent result = new Intent();
Bundle extras = new Bundle();
extras.putString("methodName", "https://bobbucks.dev/pay");
extras.putString("details", "{\"token\": \"put-some-data-here\"}");
result.putExtras(extras);
setResult(Activity.RESULT_OK, result);
finish();

您必须将两个参数指定为 intent extra：

methodName：所用方法的名称。
details：包含商家完成交易所需信息的 JSON 字符串。如果成功为 true，则必须以使 JSON.parse(details) 成功的方式构建 details。如果不需要返回任何数据，则此字符串可以是 "{}"，商家网站将会将其作为空 JavaScript 字典接收。

如果交易未在付款应用中完成（例如，用户未在付款应用中输入正确的账号 PIN 码），您可以传递 RESULT_CANCELED。浏览器可能会允许用户选择其他付款应用。

KotlinJava

setResult(Activity.RESULT_CANCELED)
finish()

setResult(Activity.RESULT_CANCELED);
finish();

如果从调用的付款应用收到的付款响应的 activity 结果设为 RESULT_OK，则 Chrome 会检查其 extras 中是否有非空 methodName 和 details。如果验证失败，Chrome 将从 request.show() 返回一个被拒绝的 promise，并显示以下面向开发者的错误消息之一：

'Payment app returned invalid response. Missing field "details".'
'Payment app returned invalid response. Missing field "methodName".'

权限

activity 可以使用其 getCallingPackage() 方法检查调用方。

KotlinJava

val caller: String? = callingPackage

String caller = getCallingPackage();

最后一步是验证调用方的签名证书，以确认调用软件包具有正确的签名。

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

您可以在 IS_READY_TO_PAY 中使用 Binder.getCallingUid() 检查调用方的软件包名称，在 PAY 中使用 Activity.getCallingPackage() 进行检查。为了实际验证调用方是否为您预期的浏览器，您应检查其签名证书，并确保其与正确的值匹配。

如果您以 API 级别 28 及更高级别为目标平台，并且要与具有单个签名证书的浏览器集成，则可以使用 PackageManager.hasSigningCertificate()。

KotlinJava

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
)

String packageName = … // The caller's package name
byte[] certificate = … // The correct signing certificate
boolean verified = packageManager.hasSigningCertificate(
        callingPackage,
        certificate,
        PackageManager.CERT_INPUT_SHA256);

对于单证书浏览器，PackageManager.hasSigningCertificate() 是首选，因为它可以正确处理证书轮替。（Chrome 只有一个签名证书。）具有多个签名证书的应用无法轮替这些证书。

如果您需要支持 API 级别 27 及更低级别，或者需要处理具有多个签名证书的浏览器，则可以使用 PackageManager.GET_SIGNATURES。

KotlinJava

val packageName: String = … // The caller's package name
val expected: Set<String> = … // The correct set of signing certificates

val packageInfo = packageManager.getPackageInfo(packageName, PackageManager.GET_SIGNATURES)
val sha256 = MessageDigest.getInstance("SHA-256")
val actual = packageInfo.signatures.map {
    SerializeByteArrayToString(sha256.digest(it.toByteArray()))
}
val verified = actual.equals(expected)

String packageName  = … // The caller's package name
Set<String> expected = … // The correct set of signing certificates

PackageInfo packageInfo =
        packageManager.getPackageInfo(packageName, PackageManager.GET_SIGNATURES);
MessageDigest sha256 = MessageDigest.getInstance("SHA-256");
Set<String> actual = new HashSet<>();
for (Signature it : packageInfo.signatures) {
    actual.add(SerializeByteArrayToString(sha256.digest(it.toByteArray())));
}
boolean verified = actual.equals(expected);

调试

使用以下命令查看错误或信息消息：

adb logcat | grep -i pay

Android 付款应用开发者指南 bookmark_borderbookmark 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

第 2 步：告知商家客户是否有已注册且可以用于付款的付款工具

AndroidManifest.xml

AIDL

实施 IsReadyToPayService

响应

权限

参数

第 3 步：让客户付款

AndroidManifest.xml

参数

methodNames

methodData

merchantName

topLevelOrigin

topLevelCertificateChain

paymentRequestOrigin

total

modifiers

paymentRequestId

响应

权限

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

调试

Android 付款应用开发者指南
bookmark_border 使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。

`AndroidManifest.xml`

实施 `IsReadyToPayService`

`AndroidManifest.xml`

`methodData`

`merchantName`

`topLevelOrigin`

`topLevelCertificateChain`

`paymentRequestOrigin`

`total`

`modifiers`

`paymentRequestId`