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

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

Sahel Sharify
Sahel Sharify
GitHub

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

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

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

浏览器可以将送货地址和联系信息的收集工作推迟到付款应用，以提供统一的付款体验。此功能称为委托。

Chrome 会尽可能将收集客户送货地址和联系信息的任务委托给调用的 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 时，这应该是一个非空 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", "john.smith@gmail.com")
    }
    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 的非空软件包，如果验证失败，则会通过 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 键的软件包，这两个键均具有字符串值
  • shippingOptions - 配送方式的 Parcelable 数组
  • error - 包含通用错误消息的字符串（例如，当 changeShippingOption 未提供有效的配送方式标识符时）
  • stringifiedPaymentMethodErrors - 表示付款方式验证错误的 JSON 字符串
  • addressErrors - 包含与送货地址和字符串值完全相同的可选键的软件包。每个键都代表与送货地址的相应部分相关的验证错误。

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