Hier erfährst du, wie Händler Zahlungs-Apps einbinden und wie Zahlungstransaktionen mit der Payment Request API funktionieren.
Web Payments APIs sind spezielle Zahlungsfunktionen, die zum ersten Mal in den Browser integriert wurden. Mit Web Payments wird die Integration von Zahlungs-Apps für Händler einfacher, während die Nutzerfreundlichkeit verbessert und die Sicherheit erhöht wird.
Weitere Informationen zu den Vorteilen von Web Payments findest du unter Zahlungs-Apps mit Web Payments optimieren.
In diesem Artikel wird eine Zahlungstransaktion auf einer Händlerwebsite beschrieben und die Einbindung von Zahlungs-Apps erläutert.
Der Prozess umfasst sechs Schritte:
- Der Händler initiiert eine Zahlungstransaktion.
- Der Händler zeigt eine Zahlungsschaltfläche an.
Der Kunde drückt die Zahlungsschaltfläche.
Der Browser startet die Zahlungs-App.
Wenn der Kunde Details ändert (z. B. Versandoptionen oder seine Adresse), aktualisiert der Händler die Transaktionsdetails entsprechend.
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 für einen Kauf entscheidet, initiiert der Händler die Zahlungstransaktion, indem er ein PaymentRequest-Objekt erstellt. Dieses Objekt enthält wichtige Informationen zur Transaktion:
- Akzeptierte Zahlungsmethoden und die zugehörigen Daten zur Abwicklung 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 des Zahlers, die E-Mail-Adresse und die Telefonnummer anfordern.
- Händler können auch den optionalen Versandtyp (
shipping,deliveryoderpickup) in diePaymentRequestaufnehmen. Die Zahlungs-App kann dies als Hinweis verwenden, um die richtigen Labels in ihrer 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'
});
Bei einigen Zahlungsabwicklern muss der Händler die Transaktions-ID angeben, die er im Voraus als Teil der Transaktionsinformationen ausgestellt hat. Eine typische Integration umfasst die Kommunikation zwischen dem Server des Händlers und dem Server des Zahlungsabwicklers, um den Gesamtpreis zu reservieren. So wird verhindert, dass böswillige Kunden den Preis manipulieren und den Händler betrügen, da am Ende der Transaktion eine Validierung erfolgt.
Der Händler kann eine Transaktions-ID als Teil des PaymentMethodData-Objekts der data-Property übergeben.
Anhand der Transaktionsinformationen sucht der Browser in der PaymentRequest nach Zahlungs-Apps, die den Zahlungsmethoden-IDs entsprechen. So kann der Browser die Zahlungs-App ermitteln, die gestartet werden soll, sobald der Händler bereit ist, die Transaktion fortzusetzen.
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 die Methoden anzeigen, die ein Kunde tatsächlich verwenden kann. Eine nicht verwendbare Zahlungsschaltfläche 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 die Schaltfläche gar nicht erst anzeigen.
Mithilfe einer PaymentRequest-Instanz kann ein Händler abfragen, ob ein Kunde die Zahlungs-App hat.
Hat der Kunde die Zahlungs-App?
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, die die Zahlungsmethode unterstützt, gefunden wurde 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 Zahlungsschaltfläche
Wenn der Kunde auf die Zahlungsschaltfläche klickt, ruft der Händler die Methode show() der Instanz PaymentRequest auf, wodurch die Zahlungsoberfläche sofort gestartet wird.
Wenn der endgültige Gesamtpreis dynamisch festgelegt wird (z. B. von einem Server abgerufen wird), kann der Händler den Start der Zahlungs-UI verschieben, bis der Gesamtpreis bekannt ist.
Start der Zahlungs-UI verschieben
Sehen Sie sich eine Demo zum Verschieben der Zahlungs-UI an, bis der endgültige Gesamtpreis feststeht.
Um die Zahlungs-UI zu verschieben, übergibt der Händler ein Promise an die Methode show().
Der Browser zeigt eine Ladeanzeige an, bis das Promise aufgelöst und die Transaktion bereit ist.
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, startet der Browser die Zahlungsoberfläche sofort.
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 werden soll, findest du hier.)
Wie die Zahlungs-App aufgebaut ist, liegt größtenteils beim Entwickler. Die Ereignisse, die vom und an den Händler gesendet werden, sowie die Struktur der Daten, die mit diesen Ereignissen weitergegeben werden, 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 kennzeichnen.
Schritt 5: Wie ein Händler die Transaktionsdetails je nach den Aktionen des Kunden aktualisieren kann
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 „Änderung der Zahlungsmethode“
- Ereignis „Änderung der Versandadresse“
- Ereignis „Änderung der Versandoption“
- Händlerüberprüfungsereignis
Ereignis „Ä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. In diesem Fall kann der Händler über das Ereignis zur Änderung der Zahlungsmethode über die neue Zahlungsmethode informiert werden, sodass 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 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 verschiedenen 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. Anhand dieses Ereignisses kann der Händler die Versandkosten basierend auf 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 ausgeben, indem er den Transaktionsdetails, die an die Zahlungs-App zurückgegeben werden, einen Fehlerparameter hinzufügt.
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ückgeben.
request.addEventListener('shippingoptionchange', e => {
e.updateWith({
// Update the details
});
});
Der Händler kann die Versandoptionen auch dynamisch an die Versandadresse des Kunden anpassen. Das ist nützlich, wenn ein Händler inländischen und internationalen Kunden unterschiedliche Versandoptionen anbieten möchte.
Händlerüberprüfungsereignis
Für zusätzliche Sicherheit kann eine Zahlungs-App eine Händlerbestätigung durchführen, bevor der Zahlungsvorgang fortgesetzt wird. Das Design des Validierungsmechanismus ist der Zahlungs-App überlassen. Das Händlervalidierungsereignis dient jedoch dazu, den Händler über die URL zu informieren, die er zur Validierung verwenden kann.
request.addEventListener('merchantvalidation', e => {
e.updateWith({
// Use `e.validateURL` to validate
});
});
Schritt 6: Der Händler validiert 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 ein PaymentResponse aufgelöst wird.
Das Objekt PaymentResponse enthält die folgenden Informationen:
- Details zum Zahlungsergebnis
- Versandadresse
- Versandoption
- Kontaktdaten
An dieser Stelle wird in der Browser-UI möglicherweise noch eine Ladeanzeige angezeigt, was bedeutet, dass die Transaktion noch nicht abgeschlossen ist.
Wenn die Zahlungs-App aufgrund eines Zahlungsfehlers beendet wird, wird das von show() zurückgegebene Promise abgelehnt und der Browser beendet die Zahlungstransaktion.
Zahlung verarbeiten und validieren
details in PaymentResponse ist das von der Zahlungs-App zurückgegebene Zahlungsinformationsobjekt. Der Händler kann die Zahlungsinformationen verwenden, um die Zahlung zu verarbeiten oder zu validieren. Wie dieser wichtige Prozess funktioniert, hängt vom Zahlungs-Handler ab.
Transaktion abschließen oder wiederholen
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 die Ladeanzeige zu schließen. - Lassen Sie den Kunden den Vorgang wiederholen, indem Sie die Methode
retry()aufrufen.
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 Zahlungsmethoden-ID findest du unter Zahlungsmethode einrichten.
- Informationen zum Erstellen einer plattformspezifischen Zahlungs-App findest du im Entwicklerhandbuch für Android-Zahlungs-Apps.
- Informationen zum Erstellen einer webbasierten Zahlungs-App finden Sie im Entwicklerhandbuch für webbasierte Zahlungs-Apps.