Lebensdauer einer Zahlungstransaktion

Hier erfährst du, 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 erleichtert und gleichzeitig die Kundenerfahrung optimiert und sicherer.

Weitere Informationen zu den Vorteilen von Web Payments findest du unter Zahlungs-Apps mit Web Payments unterstützen.

In diesem Artikel erfährst du, wie eine Zahlungstransaktion auf der Website eines Händlers ausgeführt wird und wie die Integration von Zahlungs-Apps funktioniert.

Der Prozess umfasst sechs Schritte:

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

3. Der Kunde drückt die Zahlungsschaltfläche.

   

4. Der Browser startet die Zahlungs-App.

   

5. Wenn der Kunde Details wie Versandoptionen oder Adresse ändert, aktualisiert der Händler die Transaktionsdetails mit der Änderung.

   

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 sich ein Kunde zu einem Kauf entschließt, initiiert der Händler die Zahlungstransaktion, indem er ein PaymentRequest-Objekt erstellt. Dieses Objekt enthält wichtige Informationen über die Transaktion:

• Akzeptierte Zahlungsmethoden und zugehörige Daten zur Verarbeitung der Transaktion.
• Details wie der Gesamtpreis (erforderlich) und Informationen zu den Artikeln
• Optionen, über die Händler Versandinformationen wie eine Versandadresse und Versandoption anfordern können
• Händler können auch die Rechnungsadresse, den Namen des Zahlungspflichtigen, die E-Mail-Adresse und die Telefonnummer anfordern.
• Händler können auch einen optionalen Versandtyp (shipping, delivery oder pickup) in die PaymentRequest einfügen. Die Zahlungs-App kann dies als Hinweis verwenden, um die richtigen Labels in ihrer UI 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 hinzufügen

Bei einigen Zahlungs-Handlern muss der Händler unter Umständen die im Voraus ausgestellte Transaktions-ID als Teil der Transaktionsinformationen angeben. Eine typische Integration beinhaltet die Kommunikation zwischen dem Server des Händlers und dem Server des Zahlungs-Handlers zum Reservieren des Gesamtpreises. Dadurch 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 PaymentMethodData-Objekts übergeben.

Wenn die Transaktionsinformationen angegeben sind, durchläuft der Browser einen Erkennungsprozess für Zahlungs-Apps, die in PaymentRequest angegeben sind. Dies erfolgt anhand der Kennungen der Zahlungsmethode. Auf diese Weise kann der Browser bestimmen, dass die Zahlungs-App gestartet wird, sobald der Händler bereit ist, mit der Transaktion fortzufahren.

Ausführliche Informationen zur Funktionsweise der Erkennung 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 anbieten, die ein Kunde auch tatsächlich verwenden kann. Eine unbrauchbare Zahlungsschaltfläche ist eine schlechte Nutzererfahrung. 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 verfügbar hat.

Hat der Kunde die Bezahl-App verfügbar?

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

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

Schritt 3: Der Kunde drückt die Zahlungsschaltfläche

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

Wenn der endgültige Gesamtpreis dynamisch festgelegt wird (z. B. von einem Server abgerufen), kann der Händler den Start der Zahlungs-UI verschieben, bis der Gesamtbetrag bekannt ist.

Einführung der Zahlungs-UI aufschieben

Sehen Sie sich eine Demo zum Aufschieben der Zahlungs-UI bis zur Ermittlung des endgültigen Gesamtpreises an.

Zum Verschieben der Zahlungs-UI übergibt der Händler ein Promise an die Methode show(). Der Browser zeigt eine Ladeanzeige an, bis das Promise aufgelöst wird 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 Promise als Argument für show() angegeben ist, öffnet der Browser sofort die Zahlungs-UI.

Hinweis : Wenn der Zahlungs-Handler beim Festlegen des Gesamtpreises eine Transaktions-ID zurückgibt, 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 bestimmt, welche Zahlungs-App gestartet wird

Wie die Zahlungs-App erstellt wird, bleibt größtenteils dem Entwickler überlassen. Die vom und an den Händler ausgegebenen 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 PaymentRequest-Objekt übergeben wurden. Dazu gehören:

• Daten zur Zahlungsmethode
• Gesamtpreis
• Zahlungsoptionen

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

Schritt 5: Wie ein Händler die Transaktionsdetails je nach Kundenaktionen aktualisieren kann

Kunden haben die Möglichkeit, 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 empfangen kann:

• Änderung der Zahlungsmethode
• Änderungsereignis der Versandadresse
• Ereignis: Änderung der Versandoption
• Händlervalidierungsereignis

Änderung der Zahlungsmethode

Eine Zahlungs-App kann mehrere Zahlungsmethoden unterstützen und ein Händler kann je nach Kundenauswahl einen Sonderrabatt anbieten. Um diesen Anwendungsfall abzudecken, kann der Händler durch das Änderungsereignis der Zahlungsmethode über die neue Zahlungsmethode informiert werden, sodass er den Gesamtpreis mit dem Rabatt aktualisieren und an die Zahlungs-App zurücksenden kann.

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

Änderungsereignis der Versandadresse

In einer Zahlungs-App kann optional die Versandadresse des Kunden angegeben werden. Dies ist für Kunden praktisch, 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 Händlerwebsites.

Wenn ein Kunde seine Versandadresse in einer Zahlungs-App aktualisiert, nachdem die Transaktion initiiert wurde, wird ein 'shippingaddresschange'-Ereignis an den Händler gesendet. Mit diesem Ereignis kann der Händler die Versandkosten anhand der neuen Adresse ermitteln, den Gesamtpreis aktualisieren und an die Zahlungs-App zurücksenden.

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

Wenn der Händler nicht an die aktualisierte Adresse liefern kann, kann er eine Fehlermeldung ausgeben, 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, nachdem die Zahlung autorisiert wurde.

Ereignis: Änderung der Versandoption

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 Servicenamen 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 ermitteln, den Gesamtpreis aktualisieren und an die Zahlungs-App zurücksenden.

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

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

Händlervalidierungsereignis

Zur Erhöhung der Sicherheit kann eine Zahlungs-App eine Händlervalidierung durchführen, bevor sie mit dem Zahlungsvorgang fortfährt. Das Design des Validierungsmechanismus hängt von der Zahlungs-App ab, aber durch das Ereignis zur Händlervalidierung wird der Händler über die URL informiert, mit der er sich selbst validieren kann.

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

Hinweis : Die Unterstützung für Händlerbestätigungen ist auf Apple Safari beschränkt. Seit Mai 2020 wurde dieses Ereignis in Chromium-basierten Browsern nicht implementiert.

Schritt 6: Der Händler überprüft die Zahlung und schließt die Transaktion ab

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

• Details zum Zahlungsergebnis
• Versandadresse
• Versandoption
• Kontaktdaten

An dieser Stelle zeigt die Benutzeroberfläche des Browsers möglicherweise immer noch eine Ladeanzeige an, die darauf hinweist, dass die Transaktion noch nicht abgeschlossen ist.

Wenn die Zahlungsanwendung aufgrund eines Zahlungsversäumnisses oder Fehlers beendet wird, wird das von show() zurückgegebene Promise abgelehnt und der Browser beendet die Zahlungstransaktion.

Zahlung wird verarbeitet und überprüft

Das details in PaymentResponse ist das Objekt für Anmeldedaten für Zahlungen, das von der Zahlungs-App zurückgegeben wird. Der Händler kann die Anmeldedaten verwenden, um die Zahlung zu verarbeiten oder zu validieren. Wie dieser kritische Prozess funktioniert, hängt vom Zahlungs-Handler ab.

Abschluss oder Wiederholung der Transaktion

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

• Rufen Sie die Methode .complete() auf, um die Transaktion abzuschließen, und schließen Sie die Ladeanzeige.
• Lass den Kunden es noch einmal 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

• Weitere Informationen zum Deklarieren einer Zahlungsmethode-ID findest du unter Zahlungsmethode einrichten.
• Informationen zum Erstellen einer plattformspezifischen Zahlungs-App finden Sie im Entwicklerhandbuch für Android-Zahlungs-Apps.
• Informationen zum Erstellen einer webbasierten Zahlungs-App findest du im Entwicklerhandbuch für webbasierte Zahlungs-Apps.