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

So aktualisieren Sie Ihre Android-App für Zahlungen, damit die Versandadresse und die Kontaktdaten des Zahlungspflichtigen über Web Payments APIs angegeben werden.

Sahel Sharify

Die Eingabe von Versandadresse und Kontaktdaten über ein Webformular umständlich für die Kundschaft. Sie kann zu Fehlern führen und weniger Conversions erzielen zu zahlen.

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

• Nutzer können in wenigen Schritten die richtige Adresse auswählen.
• Die Adresse wird immer im standardisierten Format.
• Es ist weniger wahrscheinlich, dass Sie eine falsche Adresse angeben.

Browser können die Erfassung von Versandadressen und Kontaktdaten auf eine Zahlungs-App, um eine einheitliche Zahlungserfahrung zu bieten. Diese Funktion ist wird als Delegierung bezeichnet.

Wann immer möglich, delegiert Chrome die Abholung der Versandinformationen eines Kunden Adresse und Kontaktdaten an die aufgerufene Android-Zahlungs-App senden. Die Delegation vereinfacht den Bezahlvorgang.

Auf der Händlerwebsite können Versandoptionen und Gesamtpreis dynamisch aktualisiert werden vom Kunden für die Lieferung und den Versand Option.

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

. Wir haben Änderungen an Versandoption und Versandadresse vorgenommen. Sehen Sie sich an, wie sich dies dynamisch auf die Versandoptionen und den Gesamtpreis auswirkt.

Hinweis : Hier erfahren Sie, wie Sie eine Android-App für Zahlungen im Voraus implementieren.

So fügen Sie einer bereits vorhandenen Android-Zahlungs-App die Unterstützung für die Delegation hinzu: führen Sie die folgenden Schritte aus:

1. Deklarieren Sie unterstützte Delegierungen.
2. PAY Intent-Extras für erforderliche Zahlung parsen Optionen.
3. Erforderliche Informationen bei der Zahlung angeben Antwort.
4. [Optional] Dynamischen Ablauf unterstützen: <ph type="x-smartling-placeholder">
   </ph>
   1. Den Händler über Änderungen an der vom Nutzer gewählten Zahlungsmethode informieren, Versandadresse oder Versand .
   2. Aktualisierte Zahlungsdetails vom Händler erhalten (z. B. die angepasster Gesamtbetrag basierend auf den Kosten).

Unterstützte Delegierungen deklarieren

Der Browser muss die Liste der zusätzlichen Informationen kennen, die Ihre Zahlung die App bereitstellen kann, damit sie die Erhebung dieser Daten an deine Deklarieren Sie die unterstützten Delegierungen als <meta-data> in der AndroidManifest.xml definiert sind.

<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 werden:

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

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

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

Zusätzliche erforderliche Informationen kann der Händler über das paymentOptions -Wörterbuch. Chrome zeigt eine Liste der erforderlichen Optionen an, die Ihre App verwenden kann. durch Übergeben der folgenden Parameter an die Aktivität PAY als Intent Extras.

paymentOptions

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

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

Folgende Parameter können enthalten sein:

• requestPayerName – boolescher Wert, der angibt, ob der Name des Zahlungspflichtigen ist erforderlich.
• requestPayerPhone – boolescher Wert, der angibt, ob das Smartphone des Zahlungspflichtigen verwendet wird ist erforderlich.
• requestPayerEmail: Boolescher Wert, der angibt, ob die E-Mail-Adresse des Zahlungspflichtigen lautet ist erforderlich.
• requestShipping: Boolescher Wert, der angibt, ob Versandinformationen ist erforderlich.
• shippingType: String, der die Versandart angibt Die Versandart kann sein: "shipping", "delivery" oder "pickup". Ihre App kann diesen Hinweis in ihrer Benutzeroberfläche, wenn sie nach der Adresse des Nutzers oder der Auswahl der Versandoptionen fragt.

shippingOptions

shippingOptions ist das Paket-Array der vom Händler angegebenen Versandkosten Optionen. 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 ein Bundle mit den folgenden Schlüsseln.

• id: die Kennung der Versandoption.
• label – Das Label der Versandoption, das dem Nutzer angezeigt wird.
• amount: Das Versandkostenset, das currency und value-Schlüssel mit Zeichenfolgenwerte.
  • currency gibt die Währung der Versandkosten als Wohlgeformtes ISO4217-Format Buchstabencode aus 3 Buchstaben
  • value zeigt den Wert der Versandkosten als gültigen dezimalen monetären Wert an. Wert
• selected – Gibt an, ob die Versandoption beim Zahlungs-App mit den Versandoptionen

Alle Schlüssel mit Ausnahme von selected haben Stringwerte. selected hat einen booleschen Wert 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 sollte die erforderlichen zusätzlichen Informationen in der Antwort auf die PAY-Aktivität.

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 ist „true“.
• payerPhone: die Telefonnummer des Zahlungspflichtigen. Dies sollte ein nicht leerer String sein, wenn paymentOptions.requestPayerPhone ist „true“.
• payerEmail: die E-Mail-Adresse des Zahlungspflichtigen. Dies sollte ein nicht leerer String sein wenn paymentOptions.requestPayerEmail „true“ ist.
• shippingAddress: Die vom Nutzer angegebene Versandadresse. Dies sollte ein nicht leeres Set, wenn paymentOptions.requestShipping wahr ist. Das Paket sollten die folgenden Schlüssel haben, die verschiedene Teile in einem physischen Adresse.
  • city
  • countryCode
  • dependentLocality
  • organization
  • phone
  • postalCode
  • recipient
  • region
  • sortingCode
  • addressLine Alle Schlüssel mit Ausnahme von addressLine haben Stringwerte. Das addressLine ist ein Array von Zeichenfolgen.
• shippingOptionId: die Kennung der vom Nutzer ausgewählten Versandoption. Dieses sollte ein nicht leerer String sein, wenn paymentOptions.requestShipping wahr ist.

Zahlungsantwort validieren

Wenn die Aktivität aus einer Zahlungsantwort resultiert, die von der aufgerufenen Zahlung empfangen wurde App auf RESULT_OK gesetzt ist, sucht Chrome nach erforderlichen zusätzlichen Informationen in ihren Extras enthalten. Wenn die Überprüfung fehlschlägt, zeigt Chrome eine abgelehnte Versprechen von request.show() mit einem der folgenden für Entwickler auftretenden Fehler Nachrichten:

'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", "[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")
    }
}

Optional: Dynamischen Ablauf unterstützen

Manchmal steigen die Gesamtkosten einer Transaktion, z. B. wenn der Nutzer die Expressversandoption oder wenn in der Liste der verfügbaren oder die Preise ändern sich, wenn der Nutzer einen internationalen Versand auswählt Adresse. Wenn Ihre App die vom Nutzer ausgewählte Versandadresse oder Option anbietet, Der Händler muss in der Lage sein, den Händler über jede Versandadresse oder Option zu informieren Änderungen vornehmen und dem Nutzer die aktualisierten Zahlungsdetails anzeigen, die vom Händler).

AIDL

Wenn du den Händler über neue Änderungen informieren möchtest, verwende die PaymentDetailsUpdateService -Dienst, der in der AndroidManifest.xml-Datei von Chrome deklariert ist. Erstellen Sie für diesen Dienst zwei AIDL-Dateien mit folgendem 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);
}

Den Händler über Änderungen an der vom Nutzer gewä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
        }
    }
}

Die callingPackageName, die für den Start-Intent des Dienstes verwendet wird, kann einen der folgenden Werte haben: je nach Browser, der die Zahlung veranlasst hat, folgende Werte:

Chrome-Version	Paketname
Stabil	"com.android.chrome"
Beta	"com.chrome.beta"
Dev	"com.chrome.dev"
Canary	"com.chrome.canary"
Chrom	"org.chromium.chrome"
Google Schnellsuchfeld (ein WebLayer-Einbettungscode)	"com.google.android.googlequicksearchbox"

changePaymentMethod

Informiert den Händler über Änderungen an der vom Nutzer ausgewählten Zahlungsmethode. Die Das Paket „paymentHandlerMethodData“ enthält methodName und optional details Schlüssel, beide mit Zeichenfolgenwerten. Chrome sucht nach einem nicht leeren Set mit einem nicht leere methodName und senden Sie ein updatePaymentDetails mit einem der Folgende Fehlermeldungen über callback.updateWith werden angezeigt, wenn die Validierung fehlschlägt.

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

changeShippingOption

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

'Shipping option identifier required.'

changeShippingAddress

Informiert den Händler über Änderungen an der vom Nutzer angegebenen Versandadresse Google Chrome sucht nach einem nicht leeren shippingAddress-Bundle mit einem gültigen countryCode und senden Sie eine updatePaymentDetails mit der folgenden Fehlermeldung über callback.updateWith, wenn die Validierung fehlschlägt.

'Payment app returned invalid shipping address in response.'

Fehlermeldung zu ungültigem Status

Wenn Chrome beim Empfang einer Änderungsanfrage einen ungültigen Status erkennt Es wird callback.updateWith mit einer entfernten updatePaymentDetails aufgerufen. Set. Das Bundle enthält nur den Schlüssel error mit "Invalid state". Beispiele für einen ungültigen Status:

• Wenn Chrome noch auf die Antwort des Händlers auf eine vorherige Änderung wartet z. B. während eines laufenden Änderungsereignisses.
• Die von der Zahlungs-App bereitgestellte Versandoption-ID gehört zu keiner der die 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 PaymentRequestDetailsUpdate WebIDL-Wörterbuch (nach dem Entfernen des modifiers) enthält und enthält die folgenden optionalen Schlüssel:

• total: Ein Bundle mit den Schlüsseln currency und value. Beide Schlüssel haben Zeichenfolgenwerte
• shippingOptions – das Paket-Array von shipping Optionen
• error: ein String mit einer generischen Fehlermeldung (z.B. beim changeShippingOption hat keine gültige Kennzeichnung für die Versandoption angegeben.)
• stringifiedPaymentMethodErrors – ein JSON-String, der die Validierung darstellt Fehler für die Zahlungsmethode
• addressErrors – ein Set mit optionalen Schlüsseln, die mit dem Versand identisch sind address und String Werte. Jeder Schlüssel stellt einen Validierungsfehler in Bezug auf den zugehörigen Teil der Versandadresse.

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