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

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

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 是商家指定配送方式的可分割数组。只有当 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，此字段应为非空软件包。该软件包应包含以下键，这些键代表实际地址中的不同部分。
  • city
  • countryCode
  • dependentLocality
  • organization
  • phone
  • postalCode
  • recipient
  • region
  • sortingCode
  • addressLine 除 addressLine 之外的所有键都有字符串值。addressLine 是一个字符串数组。
• shippingOptionId - 用户选择的配送方式的标识符。如果 paymentOptions.requestShipping 为 true，则此值应为非空字符串。

验证付款响应

如果从调用的付款应用收到的付款响应的 activity 结果设为 RESULT_OK，则 Chrome 会在其 extras 中检查是否有必要的其他信息。如果验证失败，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"
测试版	"com.chrome.beta"
Dev	"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。该软件包将仅包含具有 "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 - 包含与送货地址和字符串值完全相同的可选键的软件包。每个键都代表与送货地址的相应部分相关的验证错误。

键不存在表示其值未更改。