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

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

So aktualisieren Sie Ihre Android-Zahlungs-App, damit die Versandadresse und die Kontaktdaten des Zahlungspflichtigen an die Web Payments APIs übergeben werden.

Sahel Sharify

Veröffentlicht: 17. Juli 2020, letzte Aktualisierung: 27. Mai 2025

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. Das 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 vereinfacht.

Die Versandoptionen und der Gesamtpreis können auf der Händlerwebsite dynamisch aktualisiert werden, je nachdem, welche Versandadresse und welche Versandoption der Kunde auswählt.

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. Geben Sie 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 Bevollmächtigungen deklarieren

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

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

android:resource muss auf eine <string-array> verweisen, die alle oder einen Teil der folgenden Werte enthält:

• 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="chromium_payment_supported_delegations">
    <item>payerEmail</item>
    <item>shippingAddress</item>
  </string-array>
</resources>

PAY-Intent-Ergänzungen 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, indem die paymentOptions Intent-Extras an die PAY-Aktivität übergeben werden.

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

Bundle paymentOptions = extras.getBundle("paymentOptions");
if (paymentOptions != null) {
    Boolean requestPayerName = paymentOptions.getBoolean("requestPayerName");
    Boolean requestPayerPhone = paymentOptions.getBoolean("requestPayerPhone");
    Boolean requestPayerEmail = paymentOptions.getBoolean("requestPayerEmail");
    Boolean requestShipping = paymentOptions.getBoolean("requestShipping");
    String shippingType = paymentOptions.getString("shippingType");
}

Sie 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: Gibt an, 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)
    }

Parcelable[] shippingOptions = extras.getParcelableArray("shippingOptions");
for (Parcelable it : shippingOptions) {
  if (it != null && it instanceof Bundle) {
    Bundle shippingOption = (Bundle) it;
  }
}

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 ISO4217 an.
  • value gibt den Wert der Versandkosten als gültigen Dezimalwert an.
• selected – Gibt an, ob die Versandoption ausgewählt werden soll, wenn die Zahlungs-App die Versandoptionen anzeigt.

Alle Schlüssel außer 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)

String id = bundle.getString("id");
String label = bundle.getString("label");
Bundle amount = bundle.getBundle("amount");
Boolean selected = 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. Dieser String darf nicht leer sein, wenn paymentOptions.requestPayerName wahr ist.
• payerPhone: Telefonnummer des Zahlungspflichtigen. Wenn paymentOptions.requestPayerPhone wahr ist, sollte dies ein nicht leerer String sein.
• payerEmail: E-Mail-Adresse des Zahlungspflichtigen. Dieser String darf nicht leer sein, wenn paymentOptions.requestPayerEmail wahr ist.
• shippingAddress: Die vom Nutzer angegebene Versandadresse. Wenn paymentOptions.requestShipping wahr ist, sollte dies ein nicht leeres Bundle sein. Das Bundle sollte die folgenden Schlüssel enthalten, die verschiedene Teile einer physischen Adresse darstellen.
  • countryCode
  • postalCode
  • sortingCode
  • region
  • city
  • dependentLocality
  • addressLine
  • organization
  • recipient
  • phone 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", "5555555555")
    }
    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", "5555555555")
        putExtra("shippingAddress", address)
        putExtra("shippingOptionId", "standard")
    }
}

private Intent populateRequestedPaymentOptions() {
    Intent result = new Intent();
    if (requestPayerName) {
        result.putExtra("payerName", "John Smith");
    }
    if (requestPayerPhone) {
        presult.utExtra("payerPhone", "5555555555");
    }
    if (requestPayerEmail) {
        result.putExtra("payerEmail", "john.smith@gmail.com");
    }
    if (requestShipping) {
        Bundle address = new Bundle();
        address.putExtra("countryCode", "CA");
        address.putExtra("postalCode", "M5H2G4");
        address.putExtra("region", "Ontario");
        address.putExtra("city", "Toronto");
        String[] addressLines = new String[] {"111 Richmond st. West"};
        address.putExtra("addressLines", addressLines);
        address.putExtra("recipient", "John Smith");
        address.putExtra("phone", "5555555555");
        result.putExtra("shippingAddress", address);
        result.putExtra("shippingOptionId", "standard");
    }
    return result;
}

Optional: Dynamischen Ablauf unterstützen

Manchmal erhöhen sich die Gesamtkosten einer Transaktion, z. B. wenn der Nutzer die Option für den Expressversand 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.

Wenn Sie den Händler über neue Änderungen informieren möchten, implementieren Sie die IPaymentDetailsUpdateServiceCallback-Benutzeroberfläche und deklarieren Sie sie in Ihrer AndroidManifest.xml mit dem UPDATE_PAYMENT_DETAILS-Intent-Filter.

Unmittelbar nach dem Aufruf der PAY-Intent stellt Chrome eine Verbindung zum UPDATE_PAYMENT_DETAILS-Dienst her (falls vorhanden), der sich im selben Paket wie die PAY-Intent befindet, und ruft setPaymentDetailsUpdateService(service) auf, um Ihrer Zahlungs-App den IPaymentDetailsUpdateService-Endpunkt zur Verfügung zu stellen, um über Änderungen an der Zahlungsmethode, Versandoption oder Versandadresse des Nutzers zu informieren.

Verwenden Sie packageManager.getPackagesForUid(Binder.getCallingUid()) beim Empfangen von Inter-Process Communication (IPC), um zu prüfen, ob die App, die die PAY-Intent aufgerufen hat, denselben Paketnamen hat wie die App, die die IPaymentDetailsUpdateServiceCallback-Methoden aufgerufen hat.

AIDL

Erstellen Sie zwei AIDL-Dateien mit folgendem Inhalt:

org/chromium/components/payments/IPaymentDetailsUpdateServiceCallback.aidl

package org.chromium.components.payments;

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

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

    oneway void paymentDetailsNotUpdated();

    oneway void setPaymentDetailsUpdateService(IPaymentDetailsUpdateService service);
}

org/chromium/components/payments/IPaymentDetailsUpdateService.aidl

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

Dienst

Implementiere den Dienst IPaymentDetailsUpdateServiceCallback.

class SampleUpdatePaymentDetailsCallbackService : Service() {
    private val binder = object : IPaymentDetailsUpdateServiceCallback.Stub() {
        override fun updateWith(updatedPaymentDetails: Bundle) {}

        override fun paymentDetailsNotUpdated() {}

        override fun setPaymentDetailsUpdateService(service: IPaymentDetailsUpdateService) {}
    }

    override fun onBind(intent: Intent?): IBinder? {
        return binder
    }
}

import org.chromium.components.paymsnts.IPaymentDetailsUpdateServiceCallback;

public class SampleUpdatePaymentDetailsCallbackService extends Service {
    private final IPaymentDetailsUpdateServiceCallback.Stub mBinder =
        new IPaymentDetailsUpdateServiceCallback.Stub() {
            @Override
            public void updateWith(Bundle updatedPaymentDetails) {}

            @Override
            public void paymentDetailsNotUpdated() {}

            @Override
            public void setPaymentDetailsUpdateService(IPaymentDetailsUpdateService service) {}
        };

    @Override
    public IBinder onBind(Intent intent) {
        return mBinder;
    }
}

AndroidManifest.xml

Stellen Sie den Dienst für IPaymentDetailsUpdateServiceCallback in Ihrem AndroidManifest.xml bereit.

<service
    android:name=".SampleUpdatePaymentDetailsCallbackService"
    android:exported="true">
    <intent-filter>
        <action android:name="org.chromium.intent.action.UPDATE_PAYMENT_DETAILS" />
    </intent-filter>
</service>

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

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
}

if (service == null) {
  return;
}

try {
    if (isOptionChange) {
        service.changeShippingOption(selectedOptionId, callback);
    } else (isAddressChange) {
        service.changeShippingAddress(selectedAddress, callback);
    } else {
        service.changePaymentMethod(methodData, callback);
    }
} catch (RemoteException e) {
    // Handle the remote exception
}

changePaymentMethod

Benachrichtigt den Händler über Änderungen an der vom Nutzer ausgewählten Zahlungsmethode. Das paymentHandlerMethodData-Bundle enthält die Schlüssel methodName und optional details, beide 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 prüft, ob shippingOptionId nicht leer ist, und sendet bei einem Fehler eine updatePaymentDetails mit der folgenden Fehlermeldung über callback.updateWith.

'Shipping option identifier required.'

changeShippingAddress

Der Händler wird über Änderungen an der vom Nutzer angegebenen Lieferadresse benachrichtigt. Chrome prüft, ob ein nicht leeres shippingAddress-Bundle mit einem gültigen countryCode vorhanden ist, und sendet bei einem Fehler bei der Validierung eine updatePaymentDetails mit der folgenden Fehlermeldung über callback.updateWith.

'Payment app returned invalid shipping address in response.'

Fehlermeldung „Ungültiger Status“

Wenn Chrome beim Empfang einer Änderungsanfrage einen ungültigen Status erkennt, ruft er callback.updateWith mit einem entfernten updatePaymentDetails-Bundle auf. Das Set enthält nur den Schlüssel error 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

override fun updateWith(updatedPaymentDetails: Bundle) {}

override fun paymentDetailsNotUpdated() {}

@Override
public void updateWith(Bundle updatedPaymentDetails) {}

@Override
public void paymentDetailsNotUpdated() {}

updatedPaymentDetails ist das Bundle, das dem Wörterbuch PaymentRequestDetailsUpdate WebIDL entspricht. Es 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 für das Paket verfügbar sind
• error: Ein String mit einer allgemeinen Fehlermeldung (z.B. wenn changeShippingOption keine gültige Kennung für die Versandoption enthält)
• 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 im Zusammenhang mit dem entsprechenden Teil der Lieferadresse.
• modifiers: Ein teilbares Array von Paketen, die jeweils ein total- und ein methodData-Feld enthalten, die ebenfalls Pakete sind.

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