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 zum ersten Mal in den Browser integriert sind. Mit Web Payments wird die Einbindung von Händlern in Zahlungs-Apps vereinfacht und die Nutzerfreundlichkeit optimiert und sicherer.

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

In diesem Artikel wird eine Zahlungstransaktion auf einer Händlerwebsite veranschaulicht und die Funktionsweise der Integration von Zahlungs-Apps erläutert.

Der Prozess umfasst sechs Schritte:

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

3. Der Kunde 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, leitet der Händler die Zahlungstransaktion ein, indem er ein PaymentRequest-Objekt erstellt. Dieses Objekt enthält wichtige Informationen zur Transaktion:

• Akzeptierte 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'
});

Transaktions-ID angeben

Einige Zahlungsabwickler verlangen möglicherweise, dass der Händler die Transaktions-ID angibt, die er im Voraus im Rahmen der Transaktionsinformationen ausgegeben hat. Eine typische Integration umfasst die Kommunikation zwischen dem Server des Händlers und dem des Zahlungsabwicklers, um den Gesamtpreis zu reservieren. So wird verhindert, dass böswillige Kunden den Preis manipulieren und den Händler mit einer Bestätigung am Ende der Transaktion betrügen.

Der Händler kann eine Transaktions-ID als Teil der Property data des Objekts PaymentMethodData übergeben.

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 voraussehen 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 gar 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.

Hinweis : Wenn der Zahlungsabwickler so konfiguriert ist, dass beim Festlegen des Gesamtpreises eine Transaktions-ID zurückgegeben wird, kann die ID als Teil des Promise-Ergebnisses übergeben werden.

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, erhält sie die Transaktionsinformationen, die in Schritt 1 an das PaymentRequest-Objekt übergeben wurden. Dazu gehören:

• Daten zur Zahlungsmethode
• Gesamtpreis
• Zahlungsoptionen

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

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“
• Ereignis „Händlerüberprüfung“

Ereignis „Zahlungsmethode ändern“

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

Ereignis „Ä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 ihren bevorzugten Zahlungs-Apps speichern können, anstatt auf mehreren verschiedenen Händlerwebsites.

Wenn ein Kunde seine Lieferadresse in einer Zahlungs-App aktualisiert, nachdem die Transaktion gestartet wurde, wird ein 'shippingaddresschange'-Ereignis an den Händler 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.

Hinweis : Händler erhalten die vollständige Versandadresse des Kunden erst, wenn sie die Zahlung autorisiert haben.

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 €

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. Dies ist nützlich, wenn ein Händler unterschiedliche Versandoptionen für inländische und internationale Kunden anbieten möchte.

Ereignis „Händlerüberprüfung“

Für zusätzliche Sicherheit kann eine Zahlungs-App eine Händlerüberprüfung durchführen, bevor der Zahlungsvorgang fortgesetzt wird. Die Ausgestaltung des Validierungsmechanismus obliegt 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
  });
});

Hinweis : Das Ereignis „Händlerüberprüfung“ wird nur in Apple Safari unterstützt. In Chromium-basierten Browsern wurde dieses Ereignis bis Mai 2020 nicht implementiert.

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

Wenn der Kunde die Zahlung autorisiert hat, gibt die show()-Methode ein Versprechen zurück, das zu einer PaymentResponse führt. 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.