通过 Android 付款应用提供送货和联系信息

如何使用 Web Payments API 更新您的 Android 付款应用，以提供送货地址和付款人联系信息。

Sahel Sharify

通过网络表单输入送货地址和联系信息可能会给客户带来麻烦。这可能会导致错误和转化率降低。

因此，Payment Request API 支持请求送货地址和联系信息的功能。这样做有诸多好处：

• 用户只需点按几下就能选择正确的地址。
• 地址始终以标准化格式返回。
• 提交错误的地址不太可能会发生。

浏览器可以延迟收集送货地址和联系信息，以提供统一的付款体验。此功能称为“委托”。

Chrome 会尽可能将收集客户的送货地址和联系信息委托给调用的 Android 付款应用。此委托可减少结账过程中的不便。

商家网站可以根据客户选择的送货地址和运费选项动态更新运费选项和总价。

配送选项和送货地址实际更改。了解它如何影响运费选项和总价。

注意 ：您可以提前了解如何实现 Android 付款应用。

如需为现有的 Android 付款应用添加委托支持，请执行以下步骤：

1. 声明支持的委托。
2. 解析 PAY intent extra，以获取所需的付款方式。
3. 在付款响应中提供所需信息。
4. [可选] 支持动态流程：
   1. 通知商家用户所选付款方式、送货地址或运费选项的变化。
   2. 从商家接收更新后的付款信息（例如，根据所选运费选项的费用调整的总金额）。

声明支持的委托

浏览器需要知道您的付款应用可以提供的其他信息列表，以便将这些信息的收集委托给您的应用。请在应用的 AndroidManifest.xml 中将支持的委托声明为 <meta-data>。

<activity
  android:name=".PaymentActivity"
  …
  <meta-data
    android:name="org.chromium.payment_supported_delegations"
    android:resource="@array/supported_delegations" />
</activity>

<resource> 必须是从以下有效值中选择的字符串列表：

[ "payerName", "payerEmail", "payerPhone", "shippingAddress" ]

以下示例只能提供送货地址和付款人的电子邮件地址。

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string-array name="supported_delegations">
    <item>payerEmail</item>
    <item>shippingAddress</item>
  </string-array>
</resources>

解析了 PAY intent extra 以了解必需的付款方式

商家可以使用 paymentOptions 字典指定其他必需信息。Chrome 会将以下参数作为 Intent extra 传递给 PAY activity，从而提供应用能够提供的必需选项列表。

paymentOptions

paymentOptions 是您的应用声明支持委托的商家指定付款方式的子集。

val paymentOptions: Bundle? = extras.getBundle("paymentOptions")
val requestPayerName: Boolean? = paymentOptions?.getBoolean("requestPayerName")
val requestPayerPhone: Boolean? = paymentOptions?.getBoolean("requestPayerPhone")
val requestPayerEmail: Boolean? = paymentOptions?.getBoolean("requestPayerEmail")
val requestShipping: Boolean? = paymentOptions?.getBoolean("requestShipping")
val shippingType: String? = paymentOptions?.getString("shippingType")

它可以包含以下参数：

• requestPayerName - 布尔值，指示是否需要付款人的姓名。
• requestPayerPhone - 布尔值，指示是否需要付款人的电话号码。
• requestPayerEmail - 布尔值，指示是否需要付款人的电子邮件地址。
• requestShipping - 表示是否需要提供配送信息的布尔值。
• shippingType - 显示运费类型的字符串。配送类型可以是 "shipping"、"delivery" 或 "pickup"。在请求用户的地址或配送选项时，您的应用可以在其界面中使用此提示。

shippingOptions

shippingOptions 是商家指定的运费选项的 Parcelable 数组。只有当 paymentOptions.requestShipping == true 时，此参数才存在。

val shippingOptions: List<ShippingOption>? =
    extras.getParcelableArray("shippingOptions")?.mapNotNull {
        p -> from(p as Bundle)
    }

每个运费选项都是一个 Bundle，其中包含以下键。

• id - 送货方式标识符。
• label - 向用户显示的配送选项标签。
• amount - 运费捆绑包，包含具有字符串值的 currency 和 value 键。
  • currency 以格式正确的 ISO4217 格式（由 3 个字母组成）显示运费的币种
  • value 显示运费的金额，采用有效的十进制货币价值
• selected - 当付款应用显示运费选项时，是否应选择运费选项。

除 selected 之外的所有键都具有字符串值。selected 具有布尔值。

val id: String = bundle.getString("id")
val label: String = bundle.getString("label")
val amount: Bundle = bundle.getBundle("amount")
val selected: Boolean = bundle.getBoolean("selected", false)

在付款响应中提供所需信息

应用应在对 PAY activity 的响应中添加必需的额外信息。

为此，必须将以下参数指定为 intent extra：

• payerName - 付款人的全名。当 paymentOptions.requestPayerName 为 true 时，它应该是非空字符串。
• payerPhone - 付款人的电话号码。当 paymentOptions.requestPayerPhone 为 true 时，它应该是非空字符串。
• payerEmail - 付款人的电子邮件地址。当 paymentOptions.requestPayerEmail 为 true 时，它应该是非空字符串。
• shippingAddress - 用户提供的送货地址。当 paymentOptions.requestShipping 为 true 时，这应该是一个非空 bundle。该软件包应包含以下键，这些键分别代表一个物理地址中的不同部分。
  • city
  • countryCode
  • dependentLocality
  • organization
  • phone
  • postalCode
  • recipient
  • region
  • sortingCode
  • addressLine 除 addressLine 之外的所有键都具有字符串值。addressLine 是一个字符串数组。
• shippingOptionId - 用户选择的运费选项的标识符。当 paymentOptions.requestShipping 为 true 时，它应该是非空字符串。

验证付款响应

如果从调用的付款应用收到的付款响应的活动结果设置为 RESULT_OK，则 Chrome 将检查其 extra 中是否存在所需的其他信息。如果验证失败，Chrome 将从 request.show() 返回被拒绝的 promise，并显示以下面向开发者的错误消息之一：

'Payment app returned invalid response. Missing field "payerEmail".'
'Payment app returned invalid response. Missing field "payerName".'
'Payment app returned invalid response. Missing field "payerPhone".'
'Payment app returned invalid shipping address in response.'
'... is not a valid CLDR country code, should be 2 upper case letters [A-Z]'
'Payment app returned invalid response. Missing field "shipping option".'

以下代码示例为有效响应的示例：

fun Intent.populateRequestedPaymentOptions() {
    if (requestPayerName) {
        putExtra("payerName", "John Smith")
    }
    if (requestPayerPhone) {
        putExtra("payerPhone", "4169158200")
    }
    if (requestPayerEmail) {
        putExtra("payerEmail", "[e-mail]")
    }
    if(requestShipping) {
        val address: Bundle = Bundle()
        address.putString("countryCode", "CA")
        val addressLines: Array<String> =
                arrayOf<String>("111 Richmond st. West")
        address.putStringArray("addressLines", addressLines)
        address.putString("region", "Ontario")
        address.putString("city", "Toronto")
        address.putString("postalCode", "M5H2G4")
        address.putString("recipient", "John Smith")
        address.putString("phone", "4169158200")
        putExtra("shippingAddress", address)
        putExtra("shippingOptionId", "standard")
    }
}

可选：支持动态流程

有时，交易的总费用会增加，例如，当用户选择极速配送选项时，或者当用户选择国际送货地址时，可用配送选项的列表或其价格发生变化。当应用提供用户选择的送货地址或选项时，应能够通知商家有关送货地址或选项的任何变化，并向用户显示更新后的付款信息（由商家提供）。

AIDL

如需将新更改告知商家，请使用 Chrome 的 AndroidManifest.xml 中声明的 PaymentDetailsUpdateService 服务。如需使用此服务，请创建两个包含以下内容的 AIDL 文件：

app/src/main/aidl/org/chromium/components/payments/IPaymentDetailsUpdateService

package org.chromium.components.payments;
import android.os.Bundle;

interface IPaymentDetailsUpdateServiceCallback {
    oneway void updateWith(in Bundle updatedPaymentDetails);

    oneway void paymentDetailsNotUpdated();
}

app/src/main/aidl/org/chromium/components/payments/IPaymentDetailsUpdateServiceCallback

package org.chromium.components.payments;
import android.os.Bundle;
import org.chromium.components.payments.IPaymentDetailsUpdateServiceCallback;

interface IPaymentDetailsUpdateService {
    oneway void changePaymentMethod(in Bundle paymentHandlerMethodData,
            IPaymentDetailsUpdateServiceCallback callback);

    oneway void changeShippingOption(in String shippingOptionId,
            IPaymentDetailsUpdateServiceCallback callback);

    oneway void changeShippingAddress(in Bundle shippingAddress,
            IPaymentDetailsUpdateServiceCallback callback);
}

通知商家用户所选付款方式、送货地址或运费选项的变化

private fun bind() {
    // The action is introduced in Chrome version 92, which supports the service in Chrome
    // and other browsers (e.g., WebLayer).
    val newIntent = Intent("org.chromium.intent.action.UPDATE_PAYMENT_DETAILS")
        .setPackage(callingBrowserPackage)
    if (packageManager.resolveService(newIntent, PackageManager.GET_RESOLVED_FILTER) == null) {
        // Fallback to Chrome-only approach.
        newIntent.setClassName(
            callingBrowserPackage,
            "org.chromium.components.payments.PaymentDetailsUpdateService")
        newIntent.action = IPaymentDetailsUpdateService::class.java.name
    }
    isBound = bindService(newIntent, connection, Context.BIND_AUTO_CREATE)
}

private val connection = object : ServiceConnection {
    override fun onServiceConnected(className: ComponentName, service: IBinder) {
        val service = IPaymentDetailsUpdateService.Stub.asInterface(service)
        try {
            if (isOptionChange) {
                service?.changeShippingOption(selectedOptionId, callback)
            } else (isAddressChange) {
                service?.changeShippingAddress(selectedAddress, callback)
            } else {
                service?.changePaymentMethod(methodData, callback)
            }
        } catch (e: RemoteException) {
            // Handle the remote exception
        }
    }
}

用于服务启动 intent 的 callingPackageName 可以具有以下值之一，具体取决于发起了付款请求的浏览器。

Chrome 渠道	软件包名称
稳定	"com.android.chrome"
Beta 版	"com.chrome.beta"
开发版	"com.chrome.dev"
Canary 版	"com.chrome.canary"
Chromium	"org.chromium.chrome"
Google 快速搜索框（一种 WebLayer 嵌入器）	"com.google.android.googlequicksearchbox"

changePaymentMethod

在用户选择的付款方式发生变化时通知商家。paymentHandlerMethodData 软件包包含具有字符串值的 methodName 和可选的 details 键。Chrome 将检查是否有包含非空 methodName 的非空 bundle，如果验证失败，则会通过 callback.updateWith 发送 updatePaymentDetails，并显示以下错误消息之一。

'Method data required.'
'Method name required.'

changeShippingOption

通知商家用户选择的运费选项的变化。 shippingOptionId 应该是商家指定的某个配送选项的标识符。Chrome 将检查是否有非空 shippingOptionId，如果验证失败，则会通过 callback.updateWith 发送 updatePaymentDetails 以及以下错误消息。

'Shipping option identifier required.'

changeShippingAddress

通知商家用户提供的送货地址的变化。Chrome 将检查是否有包含有效 countryCode 的非空 shippingAddress 软件包，如果验证失败，则会通过 callback.updateWith 发送 updatePaymentDetails 及以下错误消息。

'Payment app returned invalid shipping address in response.'

“状态无效”错误消息

如果 Chrome 在收到任何更改请求时遇到无效状态，它会使用隐去的 updatePaymentDetails 软件包调用 callback.updateWith。该 bundle 将仅包含带有 "Invalid state" 的 error 键。无效状态的示例如下：

• Chrome 仍在等待商家对先前的更改（例如进行中的更改事件）的响应时。
• 付款应用提供的配送选项标识符不属于商家指定的任何配送选项。

从商家接收更新后的付款信息

private fun unbind() {
    if (isBound) {
        unbindService(connection)
        isBound = false
    }
}

private val callback: IPaymentDetailsUpdateServiceCallback =
    object : IPaymentDetailsUpdateServiceCallback.Stub() {
        override fun paymentDetailsNotUpdated() {
            // Payment request details have not changed.
            unbind()
        }

        override fun updateWith(updatedPaymentDetails: Bundle) {
            newPaymentDetails = updatedPaymentDetails
            unbind()
        }
    }

updatePaymentDetails 是相当于 PaymentRequestDetailsUpdate WebIDL 字典的软件包（在隐去 modifiers 字段后），并包含以下可选键：

• total - 包含 currency 和 value 键的 bundle，这两个键都具有字符串值
• shippingOptions - 运费选项的 Parcelable 数组
• error - 包含一般错误消息的字符串（例如，当 changeShippingOption 未提供有效的运费选项标识符时）
• stringifiedPaymentMethodErrors - 表示付款方式验证错误的 JSON 字符串
• addressErrors - 包含与送货地址和字符串值完全相同的可选键的软件包。每个键都表示一个与送货地址的相应部分相关的验证错误。

如果缺少键，则意味着该键的值未更改。