Versand- und Kontaktdaten über eine Android-Zahlungs-App angeben

So aktualisieren Sie Ihre Android-Zahlungs-App, um die Versandadresse und die Kontaktdaten des Zahlungspflichtigen mit Web Payments APIs bereitzustellen.

Sahel Sharify

Das Eingeben der Versandadresse und Kontaktdaten über ein Webformular kann für Kunden mühsam sein. Das kann zu Fehlern und einer niedrigeren Conversion-Rate führen.

Aus diesem Grund unterstützt die Payment Request API eine Funktion zum Anfordern der Lieferadresse und Kontaktdaten. Dies bietet mehrere Vorteile:

• Nutzer können mit nur wenigen Tippaktionen die richtige Adresse auswählen.
• Die Adresse wird immer im standardisierten Format zurückgegeben.
• Die Wahrscheinlichkeit, dass eine falsche Adresse angegeben wird, ist geringer.

Browser können die Erhebung der Versandadresse und der Kontaktdaten an eine Zahlungs-App weiterleiten, um eine einheitliche Zahlungsoberfläche bereitzustellen. Diese Funktion wird als Delegierung bezeichnet.

Nach Möglichkeit delegiert Chrome die Erhebung der Versandadresse und Kontaktdaten eines Kunden an die aufgerufene Android-Zahlungs-App. Dadurch wird der Bezahlvorgang reibungsloser.

Auf der Händlerwebsite können die Versandoptionen und der Gesamtpreis je nach ausgewählter Versandadresse und Versandoption dynamisch aktualisiert werden.

So fügen Sie einer vorhandenen Android-Zahlungs-App die Unterstützung für die Deaktivierung hinzu:

1. Unterstützte Delegierungen angeben
2. Parsen Sie PAY-Intent-Extras auf erforderliche Zahlungsoptionen.
3. Gib die erforderlichen Informationen in der Zahlungsantwort an.
4. [Optional] Dynamischen Ablauf unterstützen:
   1. Benachrichtigen Sie den Händler über Änderungen an der vom Nutzer ausgewählten Zahlungsmethode, Versandadresse oder Versandoption.
   2. Aktualisierte Zahlungsdetails vom Händler erhalten (z. B. den angepassten Gesamtbetrag basierend auf den Kosten der ausgewählten Versandoption)

Unterstützte Delegierungen deklarieren

Der Browser muss die Liste der zusätzlichen Informationen kennen, die Ihre Zahlungs-App zur Verfügung stellt, damit sie die Erhebung dieser Informationen an Ihre App delegieren kann. Deklarieren Sie die unterstützten Delegierungen in der Datei AndroidManifest.xml Ihrer App als <meta-data>.

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

<resource> muss eine Liste von Strings sein, die aus den folgenden gültigen Werten ausgewählt wurden:

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

Im folgenden Beispiel können nur eine Versandadresse und die E-Mail-Adresse des Zahlungspflichtigen angegeben werden.

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

PAY-Intent-Extras für erforderliche Zahlungsoptionen parsen

Der Händler kann über das paymentOptions-Wörterbuch zusätzliche erforderliche Informationen angeben. Chrome stellt eine Liste der erforderlichen Optionen bereit, die Ihre App bereitstellen kann. Dazu müssen Sie die folgenden Parameter als Intent-Extras an die PAY-Aktivität übergeben.

paymentOptions

paymentOptions ist die Teilmenge der vom Händler angegebenen Zahlungsoptionen, für die Ihre App die Unterstützung der Deaktivierung erklärt hat.

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")

Es kann die folgenden Parameter enthalten:

• requestPayerName: Gibt an, ob der Name des Zahlungspflichtigen erforderlich ist.
• requestPayerPhone: Gibt an, ob das Smartphone des Zahlungspflichtigen erforderlich ist.
• requestPayerEmail: Gibt an, ob die E-Mail-Adresse des Zahlungspflichtigen erforderlich ist.
• requestShipping: Der boolesche Wert, der angibt, ob Versandinformationen erforderlich sind.
• shippingType: Der String, der den Versandtyp angibt. Der Versandtyp kann "shipping", "delivery" oder "pickup" sein. Dieser Hinweis kann in der Benutzeroberfläche Ihrer App verwendet werden, wenn Sie nach der Adresse des Nutzers oder nach den Versandoptionen fragen.

shippingOptions

shippingOptions ist das Array der vom Händler angegebenen Versandoptionen, die sich in Pakete verpacken lassen. Dieser Parameter ist nur vorhanden, wenn paymentOptions.requestShipping == true.

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

Jede Versandoption ist eine Bundle mit den folgenden Schlüsseln.

• id: Die Kennung der Versandoption.
• label: Das Label der Versandoption, das dem Nutzer angezeigt wird.
• amount: Das Paket mit Versandkosten, das die Schlüssel currency und value mit Stringwerten enthält.
  • currency gibt die Währung der Versandkosten als korrekt formatierten dreistelligen alphabetischen ISO 4217-Code an.
  • value gibt den Wert der Versandkosten als gültigen Dezimalwert an.
• selected: Gibt an, ob die Versandoption ausgewählt werden soll, wenn die Versandoptionen in der Zahlungs-App angezeigt werden.

Alle Schlüssel mit Ausnahme von selected haben Stringwerte. selected hat einen booleschen Wert.

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)

Erforderliche Informationen in einer Zahlungsantwort angeben

Ihre App muss die erforderlichen zusätzlichen Informationen in der Antwort auf die PAY-Aktivität enthalten.

Dazu müssen die folgenden Parameter als Intent-Extras angegeben werden:

• payerName: Der vollständige Name des Zahlungspflichtigen. Dies sollte ein nicht leerer String sein, wenn paymentOptions.requestPayerName wahr ist.
• payerPhone: Telefonnummer des Zahlungspflichtigen. Dieser String darf nicht leer sein, wenn paymentOptions.requestPayerPhone wahr ist.
• payerEmail: E-Mail-Adresse des Zahlungspflichtigen. Dies sollte ein nicht leerer String sein, wenn paymentOptions.requestPayerEmail wahr ist.
• shippingAddress: Die vom Nutzer angegebene Versandadresse. Dies sollte ein nicht leeres Bundle sein, wenn paymentOptions.requestShipping wahr ist. Das Bundle sollte die folgenden Schlüssel enthalten, die verschiedene Teile in einer physischen Adresse darstellen.
  • city
  • countryCode
  • dependentLocality
  • organization
  • phone
  • postalCode
  • recipient
  • region
  • sortingCode
  • addressLine Alle Schlüssel außer addressLine haben Stringwerte. addressLine ist ein Array von Strings.
• shippingOptionId: Die Kennung der vom Nutzer ausgewählten Versandoption. Dieser String darf nicht leer sein, wenn paymentOptions.requestShipping wahr ist.

Zahlungsantwort prüfen

Wenn das Aktivitätsergebnis einer Zahlungsantwort, die von der aufgerufenen Zahlungs-App empfangen wurde, auf RESULT_OK festgelegt ist, sucht Chrome in den Extras nach erforderlichen zusätzlichen Informationen. Wenn die Validierung fehlschlägt, gibt Chrome ein abgelehntes Versprechen von request.show() mit einer der folgenden Fehlermeldungen für Entwickler zurück:

'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".'

Das folgende Codebeispiel ist ein Beispiel für eine gültige Antwort:

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")
    }
}

Optional: Dynamischen Ablauf unterstützen

Manchmal steigen die Gesamtkosten einer Transaktion, z. B. wenn der Nutzer die Expressversandoption auswählt oder sich die Liste der verfügbaren Versandoptionen oder deren Preise ändert, wenn der Nutzer eine internationale Versandadresse auswählt. Wenn Ihre App die vom Nutzer ausgewählte Versandadresse oder -option angibt, sollte sie den Händler über Änderungen an der Versandadresse oder -option informieren und dem Nutzer die aktualisierten Zahlungsdetails (vom Händler bereitgestellt) anzeigen können.

AIDL

Verwenden Sie den PaymentDetailsUpdateService-Dienst, der in der AndroidManifest.xml-Datei von Chrome deklariert ist, um den Händler über neue Änderungen zu informieren. Erstellen Sie zum Verwenden dieses Dienstes zwei AIDL-Dateien mit dem folgenden Inhalt:

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);
}

Händler über Änderungen an der vom Nutzer ausgewählten Zahlungsmethode, Versandadresse oder Versandoption informieren

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
        }
    }
}

Der callingPackageName, der für die Startabsicht des Dienstes verwendet wird, kann einen der folgenden Werte haben, je nachdem, welcher Browser die Zahlungsanfrage initiiert hat.

changePaymentMethod

Benachrichtigt den Händler über Änderungen an der vom Nutzer ausgewählten Zahlungsmethode. Das Bundle paymentHandlerMethodData enthält methodName- und optionale details-Schlüssel mit Stringwerten. Chrome sucht nach einem nicht leeren Bundle mit einem nicht leeren methodName und sendet bei einem Validierungsfehler eine updatePaymentDetails mit einer der folgenden Fehlermeldungen über callback.updateWith.

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

changeShippingOption

Der Händler wird über Änderungen an der vom Nutzer ausgewählten Versandoption benachrichtigt. shippingOptionId sollte die Kennung einer der vom Händler angegebenen Versandoptionen sein. Chrome sucht nach einem nicht leeren shippingOptionId und sendet ein updatePaymentDetails mit der folgenden Fehlermeldung über callback.updateWith, wenn die Validierung fehlschlägt.

'Shipping option identifier required.'

changeShippingAddress

Der Händler wird über Änderungen an der vom Nutzer angegebenen Lieferadresse benachrichtigt. Chrome sucht nach einem nicht leeren shippingAddress-Bundle mit einem gültigen countryCode und sendet ein updatePaymentDetails mit der folgenden Fehlermeldung über callback.updateWith, wenn die Validierung fehlschlägt.

'Payment app returned invalid shipping address in response.'

Fehlermeldung „Ungültiger Status“

Wenn Chrome beim Empfang einer der Änderungsanfragen auf einen ungültigen Status stößt, wird callback.updateWith mit einem entfernten updatePaymentDetails-Bundle aufgerufen. Das Set enthält nur den error-Schlüssel mit "Invalid state". Beispiele für einen ungültigen Status:

• Chrome wartet noch auf die Antwort des Händlers auf eine vorherige Änderung (z. B. ein laufendes Änderungsereignis).
• Die von der Zahlungs-App bereitgestellte Versandoptionen-ID gehört nicht zu den vom Händler angegebenen Versandoptionen.

Aktualisierte Zahlungsdetails vom Händler erhalten

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 ist das Bundle, das dem Wörterbuch WebIDL PaymentRequestDetailsUpdate entspricht (nach dem Entfernen des Felds modifiers) und enthält die folgenden optionalen Schlüssel:

• total – ein Bundle mit den Schlüsseln currency und value, die beide Stringwerte haben
• shippingOptions: das Array der Versandoptionen, die sich verpacken lassen
• error: ein String mit einer allgemeinen Fehlermeldung (z.B. wenn changeShippingOption keine gültige Kennzeichnung der Versandoption angibt)
• stringifiedPaymentMethodErrors: Ein JSON-String, der Validierungsfehler für die Zahlungsmethode darstellt
• addressErrors – ein Paket mit optionalen Schlüsseln, die mit shipping address identisch sind, und Stringwerten. Jeder Schlüssel steht für einen Validierungsfehler, der sich auf den entsprechenden Teil der Versandadresse bezieht.

Ein fehlender Schlüssel bedeutet, dass sich sein Wert nicht geändert hat.