Android 付款應用程式開發人員指南

瞭解如何調整 Android 付款應用程式，讓其與網路支付服務搭配運作，為客戶提供更優質的使用者體驗。

Eiji Kitamura
Yuichi Araki
Yuichi Araki
X GitHub

Payment Request API 為網頁提供內建的瀏覽器介面，讓使用者更輕鬆地輸入必要的付款資訊。此 API 也可以叫用特定平台的付款應用程式。

瀏覽器支援

  • Chrome：60。
  • 邊緣：15。
  • Firefox：在標記後方。
  • Safari：11.1.

資料來源

使用採用網路支付的特定平台 Google Pay 應用程式進行結帳流程。

相較於僅使用 Android 意圖，使用網路付款功能可進一步整合瀏覽器、安全性和使用者體驗：

  • 付款應用程式是在商家網站上以互動模式啟動。
  • 實作可以補充現有的付款應用程式，讓您充分利用使用者族群。
  • 系統會檢查付款應用程式的簽章，以防側載。
  • 付款應用程式可支援多種付款方式。
  • 任何付款方式 (例如加密貨幣、銀行轉帳等) 都可以整合。Android 裝置上的付款應用程式甚至可以整合需要存取裝置硬體晶片的方法。

在 Android 付款應用程式中導入網路付款功能需要四個步驟：

  1. 讓商家發現您的付款應用程式。
  2. 讓商家知道客戶是否有已註冊的付款工具 (例如信用卡)，可用於付款。
  3. 讓客戶付款。
  4. 驗證呼叫者的簽署憑證。

如要瞭解 Web Payments 的實際運作情形，請查看 android-web-payment 示範。

步驟 1：讓商家發現您的付款應用程式

商家必須使用 Payment Request API，並使用付款方式 ID 指定您支援的付款方式，才能使用您的付款應用程式。

如果您有專屬於付款應用程式的付款方式 ID，可以設定自己的付款方式資訊清單，讓瀏覽器能夠發現您的應用程式。

步驟 2：讓商家知道客戶是否有已註冊的付款工具，可用於付款

商家可以呼叫 hasEnrolledInstrument()，查詢消費者是否可以付款。您可以將 IS_READY_TO_PAY 實作為 Android 服務，以便回答這項查詢。

AndroidManifest.xml

使用含有 org.chromium.intent.action.IS_READY_TO_PAY 動作的意圖篩選器宣告服務。

<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 服務為選用項目。如果付款應用程式中沒有這類意圖處理常式，網路瀏覽器就會假設應用程式隨時可以付款。

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 意圖 PAY 叫用付款應用程式，並在意圖參數中提供交易資訊。

付款應用程式會回傳 methodName 和 details，這兩者是付款應用程式專屬，對瀏覽器而言是不可見的。瀏覽器會透過 JSON 反序列化，將 details 字串轉換為商家的 JavaScript 物件，但不會強制執行任何其他有效性。瀏覽器不會修改 details；該參數的值會直接傳遞給商家。

AndroidManifest.xml

具有 PAY 意圖篩選器的活動應具有 <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>

參數

系統會將下列參數以意圖額外項目的形式傳遞至活動：

  • 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

商家的來源，不含方案 (頂層瀏覽內容的無方案來源)。例如，https://mystore.com/checkout 會以 mystore.com 的形式傳遞。

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

topLevelCertificateChain

商家的憑證鏈結 (頂層瀏覽內容的憑證鏈結)。localhost 和磁碟上的檔案為空值，這些都是沒有 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")

回應

活動可以透過 RESULT_OK 將回應傳回至 setResult。

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

您必須將兩個參數指定為 Intent 額外項目：

  • methodName：所用方法的名稱。
  • details：包含商家完成交易所需資訊的 JSON 字串。如果成功是 true，則 details 必須以 JSON.parse(details) 成功的方式建構。

如果付款應用程式未完成交易 (例如使用者無法在付款應用程式中輸入正確的帳戶 PIN 碼)，您可以傳遞 RESULT_CANCELED。瀏覽器可能會讓使用者選擇其他付款應用程式。

setResult(RESULT_CANCELED)
finish()

如果從叫用的付款應用程式收到的付款回應活動結果設為 RESULT_OK，Chrome 會檢查其額外資料中是否有非空的 methodName 和 details。如果驗證失敗，Chrome 會從 request.show() 傳回已遭拒絕的承諾，並顯示下列其中一個開發人員錯誤訊息：

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

權限

活動可以透過 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) } }