Lebensdauer einer Zahlungstransaktion

Hier erfahren Sie, wie Händler Zahlungs-Apps einbinden und wie Zahlungstransaktionen mit der Payment Request API funktionieren.

Eiji Kitamura

Milica Mihajlija

Web Payments APIs sind spezielle Zahlungsfunktionen, die erstmalig in den Browser integriert werden. Mit Web Payments wird die Händlerintegration in Zahlungs-Apps einfacher, während die Kundenerfahrung optimiert und sicherer wird.

Weitere Informationen zu den Vorteilen von Webzahlungen finden Sie im Hilfeartikel Zahlungs-Apps mit Webzahlungen optimieren.

In diesem Artikel wirst du durch eine Zahlungstransaktion auf der Website eines Händlers geführt und erfährst, wie die Einbindung von Zahlungs-Apps funktioniert.

Der Prozess umfasst sechs Schritte:

1. Der Händler initiiert eine Zahlungstransaktion.
2. Der Händler zeigt eine Zahlungsschaltfläche an.

3. Die Kundin drückt auf die Zahlungsschaltfläche.

   

4. Der Browser startet die Zahlungs-App.

   

5. Wenn der Kunde Details ändert (z. B. Versandoptionen oder seine Adresse), aktualisiert der Händler die Transaktionsdetails entsprechend.

   

6. Nachdem der Kunde den Kauf bestätigt hat, validiert der Händler die Zahlung und schließt die Transaktion ab.

   

Schritt 1: Der Händler initiiert eine Zahlungstransaktion

Wenn ein Kunde einen Kauf abschließt, initiiert der Händler die Zahlungstransaktion, indem er ein PaymentRequest-Objekt erstellt. Dieses Objekt enthält wichtige Informationen zur Transaktion:

• Zulässige Zahlungsmethoden und die zugehörigen Daten zur Verarbeitung der Transaktion.
• Details wie der Gesamtpreis (erforderlich) und Informationen zu den Artikeln.
• Optionen, mit denen Händler Versandinformationen wie eine Versandadresse und eine Versandoption anfordern können.
• Händler können auch die Rechnungsadresse, den Namen, die E-Mail-Adresse und die Telefonnummer des Zahlungspflichtigen anfordern.
• Händler können auch einen optionalen Versandtyp (shipping, delivery oder pickup) in die PaymentRequest aufnehmen. Die Zahlungs-App kann dies als Hinweis verwenden, um die richtigen Labels in der Benutzeroberfläche anzuzeigen.

const request = new PaymentRequest([{
  supportedMethods: 'https://bobpay.xyz/pay',
  data: {
    transactionId: '****'
  }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {
  requestShipping: true,
  requestBillingAddress: true,
  requestPayerEmail: true,
  requestPayerPhone: true,
  requestPayerName: true,
  shippingType: 'delivery'
});

Wenn die Transaktionsinformationen vorliegen, führt der Browser anhand der Zahlungsmethoden-IDs einen Discovery-Prozess für die in der PaymentRequest angegebenen Zahlungs-Apps durch. So kann der Browser die Zahlungs-App bestimmen, die gestartet werden soll, sobald der Händler mit der Transaktion fortfahren kann.

Weitere Informationen zur Funktionsweise des Erkennungsprozesses finden Sie unter Zahlungsmethode einrichten.

Schritt 2: Der Händler zeigt eine Zahlungsschaltfläche an

Händler können viele Zahlungsmethoden unterstützen, sollten aber nur die Zahlungsschaltflächen für diejenigen anzeigen, die ein Kunde tatsächlich verwenden kann. Eine Zahlungsschaltfläche, die nicht funktioniert, ist nicht nutzerfreundlich. Wenn ein Händler vorhersagen kann, dass eine im PaymentRequest-Objekt angegebene Zahlungsmethode für den Kunden nicht funktioniert, kann er eine Fallback-Lösung anbieten oder diese Schaltfläche überhaupt nicht anzeigen.

Mit einer PaymentRequest-Instanz kann ein Händler abfragen, ob ein Kunde die Zahlungs-App hat.

Ist die Zahlungs-App für den Kunden verfügbar?

Die Methode canMakePayment() von PaymentRequest gibt true zurück, wenn auf dem Gerät des Kunden eine Zahlungs-App verfügbar ist. „Verfügbar“ bedeutet, dass eine Zahlungs-App gefunden wurde, die die Zahlungsmethode unterstützt, und dass die plattformspezifische Zahlungs-App installiert ist oder die webbasierte Zahlungs-App registriert werden kann.

const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
  // Fallback to other means of payment or hide the button.
}

Schritt 3: Der Kunde drückt die Schaltfläche „Bezahlen“

Wenn der Kunde auf die Zahlungsschaltfläche klickt, ruft der Händler die show()-Methode der PaymentRequest-Instanz auf, wodurch sofort die Zahlungsoberfläche gestartet wird.

Wenn der endgültige Gesamtpreis dynamisch festgelegt wird (z. B. von einem Server abgerufen), kann der Händler die Anzeige der Zahlungsoberfläche so lange verzögern, bis der Gesamtpreis bekannt ist.

Einführung der Zahlungsoberfläche verschieben

Demo der Benutzeroberfläche für die Zahlung aufschieben, bis der endgültige Gesamtpreis ermittelt wurde.

Um die Zahlungsoberfläche zu verschieben, gibt der Händler ein Versprechen an die show()-Methode weiter. Im Browser wird eine Ladeanzeige angezeigt, bis das Versprechen erfüllt ist und die Transaktion beginnen kann.

const getTotalAmount = async () => {
  // Fetch the total amount from the server, etc.
};

try {
  const result = await request.show(getTotalAmount());
  // Process the result…
} catch(e) {
  handleError(e);
}

Wenn kein Versprechen als Argument für show() angegeben ist, startet der Browser sofort die Zahlungsoberfläche.

Schritt 4: Der Browser startet die Zahlungs-App

Der Browser kann eine plattformspezifische oder eine webbasierte Zahlungs-App starten. Weitere Informationen dazu, wie Chrome festlegt, welche Zahlungs-App gestartet wird

Wie die Zahlungs-App aufgebaut ist, liegt größtenteils im Ermessen des Entwicklers. Die vom Händler gesendeten und empfangenen Ereignisse sowie die Struktur der mit diesen Ereignissen übergebenen Daten sind jedoch standardisiert.

Wenn die Zahlungs-App gestartet wird, empfängt sie die Transaktionsinformationen, die in Schritt 1 an das Objekt PaymentRequest übergeben werden. Sie umfassen Folgendes:

• Daten zur Zahlungsmethode
• Gesamtpreis
• Zahlungsoptionen

Die Zahlungs-App verwendet die Transaktionsinformationen, um ihre Benutzeroberfläche zu kennzeichnen.

Schritt 5: So kann ein Händler die Transaktionsdetails je nach Aktion des Kunden aktualisieren

Kunden haben die Möglichkeit, die Transaktionsdetails wie Zahlungsmethode und Versandoption in der Zahlungs-App zu ändern. Während der Kunde Änderungen vornimmt, erhält der Händler die Änderungsereignisse und aktualisiert die Transaktionsdetails.

Es gibt vier Arten von Ereignissen, die ein Händler erhalten kann:

• Ereignis „Zahlungsmethode ändern“
• Ereignis „Änderung der Versandadresse“
• Ereignis „Versandoption ändern“
• Händlervalidierungsereignis

Änderung der Zahlungsmethode

Eine Zahlungs-App kann mehrere Zahlungsmethoden unterstützen und ein Händler kann je nach Auswahl des Kunden einen speziellen Rabatt anbieten. Für diesen Anwendungsfall kann der Händler über das Ereignis „Zahlungsmethode ändern“ über die neue Zahlungsmethode informiert werden, damit er den Gesamtpreis mit dem Rabatt aktualisieren und an die Zahlungs-App zurückgeben kann.

request.addEventListener('paymentmethodchange', e => {
  e.updateWith({
    // Add discount etc.
  });
});

Änderung der Versandadresse

Eine Zahlungs-App kann optional die Versandadresse des Kunden angeben. Das ist praktisch für Kunden, da sie keine Details manuell in ein Formular eingeben müssen und ihre Versandadresse in ihrer bevorzugten Zahlungs-App statt auf mehreren verschiedenen Händlerwebsites hinterlegen können.

Wenn ein Kunde seine Lieferadresse in einer Zahlungs-App nach Beginn der Transaktion aktualisiert, wird dem Händler ein 'shippingaddresschange'-Ereignis gesendet. Anhand dieses Ereignisses kann der Händler die Versandkosten anhand der neuen Adresse ermitteln, den Gesamtpreis aktualisieren und an die Zahlungs-App zurückgeben.

request.addEventListener('shippingaddresschange', e => {
  e.updateWith({
    // Update the details
  });
});

Wenn der Händler nicht an die aktualisierte Adresse versenden kann, kann er eine Fehlermeldung senden, indem er den Transaktionsdetails, die an die Zahlungs-App zurückgegeben werden, einen Fehlerparameter hinzufügt.

Ereignis „Versandoption ändern“

Ein Händler kann dem Kunden mehrere Versandoptionen anbieten und diese Auswahl an die Zahlungs-App delegieren. Die Versandoptionen werden als Liste mit Preisen und Dienstnamen angezeigt, aus denen der Kunde auswählen kann. Beispiel:

• Standardversand – kostenlos
• Expressversand – 5 EUR

Wenn ein Kunde die Versandoption in einer Zahlungs-App aktualisiert, wird ein 'shippingoptionchange'-Ereignis an den Händler gesendet. Der Händler kann dann die Versandkosten festlegen, den Gesamtpreis aktualisieren und die Zahlung an die Zahlungs-App zurückgeben.

request.addEventListener('shippingoptionchange', e => {
  e.updateWith({
    // Update the details
  });
});

Der Händler kann die Versandoptionen auch dynamisch anhand der Versandadresse des Kunden ändern. Das ist nützlich, wenn ein Händler unterschiedliche Versandoptionen für inländische und internationale Kunden anbieten möchte.

Händlervalidierungsereignis

Für zusätzliche Sicherheit kann eine Zahlungs-App eine Händlerbestätigung durchführen, bevor mit dem Zahlungsvorgang fortgefahren wird. Die Ausgestaltung des Validierungsmechanismus liegt in der Verantwortung der Zahlungs-App. Das Ereignis „Händlerüberprüfung“ dient jedoch dazu, den Händler über die URL zu informieren, über die er sich selbst bestätigen kann.

request.addEventListener('merchantvalidation', e => {
  e.updateWith({
    // Use `e.validateURL` to validate
  });
});

Schritt 6: Der Händler bestätigt die Zahlung und schließt die Transaktion ab

Wenn der Kunde die Zahlung erfolgreich autorisiert, gibt die Methode show() ein Promise zurück, das in PaymentResponse aufgelöst wird. Das PaymentResponse-Objekt enthält die folgenden Informationen:

• Details zum Zahlungsergebnis
• Versandadresse
• Versandoption
• Kontaktdaten

In diesem Moment wird in der Browseroberfläche möglicherweise noch ein Ladebalken angezeigt, was bedeutet, dass die Transaktion noch nicht abgeschlossen ist.

Wenn die Zahlungs-App aufgrund eines Zahlungsfehlers oder -ausfalls beendet wird, wird das von show() zurückgegebene Promise abgelehnt und der Browser beendet die Zahlungstransaktion.

Zahlung wird verarbeitet und bestätigt

Die details in PaymentResponse ist das Zahlungsdatenobjekt, das von der Zahlungs-App zurückgegeben wird. Der Händler kann die Anmeldedaten verwenden, um die Zahlung zu verarbeiten oder zu bestätigen. Wie dieser wichtige Prozess funktioniert, liegt im Ermessen des Zahlungsabwicklers.

Transaktion abschließen oder noch einmal versuchen

Nachdem der Händler festgestellt hat, ob die Transaktion erfolgreich war oder fehlgeschlagen ist, kann er Folgendes tun:

• Rufe die Methode .complete() auf, um die Transaktion abzuschließen und den Ladebalken zu schließen.
• Bitte den Kunden, es noch einmal zu versuchen, indem er die Methode retry() aufruft.

async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}

async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong…
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

Nächste Schritte

• Eine ausführliche Anleitung zum Deklarieren einer Zahlungsmethoden-ID finden Sie unter Zahlungsmethode einrichten.
• Informationen zum Erstellen einer plattformspezifischen Zahlungs-App finden Sie im Entwicklerleitfaden für Android-Zahlungs-Apps.
• Informationen zum Erstellen einer webbasierten Zahlungs-App finden Sie im Entwicklerleitfaden für webbasierte Zahlungs-Apps.