Hier erfahren Sie, wie Sie Ihre webbasierte Zahlungs-App an Web Payments anpassen und die Nutzerfreundlichkeit für Kunden verbessern können.
Sobald eine webbasierte Zahlungs-App eine Zahlungsanfrage erhält und eine Zahlungstransaktion initiiert, fungiert der Service Worker als Hub für die Kommunikation zwischen dem Händler und der Zahlungs-App. In diesem Beitrag wird erläutert, wie eine Zahlungs-App mithilfe eines Service Workers Informationen zur Zahlungsmethode, zur Versandadresse oder zu Kontaktdaten an den Händler weitergeben kann.
Händler informieren
Es ist wichtig, den Händler über die folgenden Änderungen zu informieren.
Änderung der Zahlungsmethode
Zahlungs-Apps können mehrere Zahlungsmittel mit unterschiedlichen Zahlungsmethoden unterstützen.
| Kunde | Zahlungsmethode | Zahlungsmittel |
|---|---|---|
| A | Kreditkartenaussteller 1 | ****1234 |
| Kreditkartenaussteller 1 | ****4242 |
|
| Bank X | ******123 |
|
| B | Kreditkartenaussteller 2 | ****5678 |
| Bank X | ******456 |
In der obigen Tabelle sind beispielsweise für die webbasierte Wallet von Kunde A zwei Kreditkarten und ein Bankkonto registriert. In diesem Fall verarbeitet die App drei Zahlungsmittel (****1234, ****4242, ******123) und zwei Zahlungsmethoden (Kreditkartenaussteller 1 und Bank X). Bei einer Zahlungstransaktion kann die Zahlungs-App dem Kunden die Möglichkeit geben, eines der Zahlungsmittel auszuwählen und damit den Händler zu bezahlen.
Die Zahlungs-App kann den Händler darüber informieren, welche Zahlungsmethode der Kunde ausgewählt hat, bevor die vollständige Zahlungsantwort gesendet wird. Das ist nützlich, wenn der Händler beispielsweise eine Rabattkampagne für eine bestimmte Zahlungsmethode durchführen möchte.
Mit der webbasierten Payment Handler API kann die Zahlungs-App über einen Service Worker ein Ereignis zur Änderung der Zahlungsmethode an den Händler senden, um die neue Kennung der Zahlungsmethode mitzuteilen. Der Service Worker sollte PaymentRequestEvent.changePaymentMethod() mit den neuen Zahlungsmethodeninformationen aufrufen.
Zahlungs-Apps können ein methodDetails-Objekt als optionales zweites Argument für PaymentRequestEvent.changePaymentMethod() übergeben. Dieses Objekt kann beliebige Details zur Zahlungsmethode enthalten, die der Händler zur Verarbeitung des Änderungsereignisses benötigt.
[payment handler] service-worker.js
…
// Received a message from the frontend
self.addEventListener('message', async e => {
let details;
try {
switch (e.data.type) {
…
case 'PAYMENT_METHOD_CHANGED':
const newMethod = e.data.paymentMethod;
const newDetails = e.data.methodDetails;
// Redact or check that no sensitive information is passed in
// `newDetails`.
// Notify the merchant of the payment method change
details =
await payment_request_event.changePaymentMethod(newMethod, newDetails);
…
Wenn der Händler ein paymentmethodchange-Ereignis von der Payment Request API erhält, kann er die Zahlungsdetails aktualisieren und mit einem PaymentDetailsUpdate-Objekt antworten.
[merchant]
request.addEventListener('paymentmethodchange', e => {
if (e.methodName === 'another-pay') {
// Apply $10 discount for example.
const discount = {
label: 'special discount',
amount: {
currency: 'USD',
// The value being string complies the spec
value: '-10.00'
}
};
let total = 0;
details.displayItems.push(discount);
for (let item of details.displayItems) {
total += parseFloat(item.amount.value);
}
// Convert the number back to string
details.total.amount.value = total.toString();
}
// Pass a promise to `updateWith()` and send updated payment details
e.updateWith(details);
});
Wenn der Händler antwortet, wird das von PaymentRequestEvent.changePaymentMethod() zurückgegebene Promise mit einem PaymentRequestDetailsUpdate-Objekt aufgelöst.
[payment handler] service-worker.js
…
// Notify the merchant of the payment method change
details = await payment_request_event.changePaymentMethod(newMethod, newDetails);
// Provided the new payment details,
// send a message back to the frontend to update the UI
postMessage('UPDATE_REQUEST', details);
break;
…
Verwenden Sie das Objekt, um die Benutzeroberfläche im Frontend zu aktualisieren. Siehe Aktualisierte Zahlungsdetails anzeigen.
Änderung der Versandadresse
Zahlungs-Apps können dem Händler im Rahmen einer Zahlungstransaktion die Versandadresse eines Kunden zur Verfügung stellen.
Das ist für Händler nützlich, da sie die Adresserfassung an Zahlungs-Apps delegieren können. Da die Adressdaten im Standarddatenformat bereitgestellt werden, kann der Händler davon ausgehen, dass die Versandadressen eine einheitliche Struktur haben.
Außerdem können Kunden ihre Adressinformationen in ihrer bevorzugten Zahlungs-App registrieren und für verschiedene Händler wiederverwenden.
Zahlungs-Apps können eine Benutzeroberfläche bereitstellen, über die eine Versandadresse bearbeitet oder vorab registrierte Adressinformationen für den Kunden bei einer Zahlungstransaktion ausgewählt werden können. Wenn eine Versandadresse vorübergehend festgelegt wird, kann die Zahlungs-App den Händler über die unkenntlich gemachten Adressinformationen informieren. Das bietet Händlern mehrere Vorteile:
- Ein Händler kann feststellen, ob der Kunde die regionalen Einschränkungen für den Versand des Artikels erfüllt (z. B. nur Inland).
- Ein Händler kann die Liste der Versandoptionen je nach Region der Versandadresse ändern (z. B. internationaler Standard- oder Expressversand).
- Ein Händler kann die neuen Versandkosten basierend auf der Adresse anwenden und den Gesamtpreis aktualisieren.
Mit der webbasierten Payment Handler API kann die Zahlungs-App über den Service Worker ein Ereignis zur Änderung der Versandadresse an den Händler senden, um die neue Versandadresse mitzuteilen. Der Service Worker sollte PaymentRequestEvent.changeShippingAddress() mit dem neuen Adressobjekt aufrufen.
[payment handler] service-worker.js
...
// Received a message from the frontend
self.addEventListener('message', async e => {
let details;
try {
switch (e.data.type) {
…
case 'SHIPPING_ADDRESS_CHANGED':
const newAddress = e.data.shippingAddress;
details =
await payment_request_event.changeShippingAddress(newAddress);
…
Schlüsselbegriff: Unkenntlich gemachte Adresse. In diesem Fall ist es nicht erforderlich, dem Händler die vollständige Versandadresse mitzuteilen. Außerdem wird dadurch die Privatsphäre der Kunden gefährdet. Der Händler erhält nur die Teile der Adresse, die er zur Ermittlung der Versandkosten benötigt. Konkret löscht der Browser die Felder organization, phone, recipient und addressLine aus der von der Zahlungs-App bereitgestellten Adresse, bevor das Ereignis shippingaddresschange im DOM des Händlers ausgelöst wird.
Der Händler erhält von der Payment Request API ein shippingaddresschange-Ereignis, damit er mit der aktualisierten PaymentDetailsUpdate antworten kann.
[merchant]
request.addEventListener('shippingaddresschange', e => {
// Read the updated shipping address and update the request.
const addr = request.shippingAddress;
const details = getPaymentDetailsFromShippingAddress(addr);
// `updateWith()` sends back updated payment details
e.updateWith(details);
});
Wenn der Händler antwortet, wird das zurückgegebene Promise PaymentRequestEvent.changeShippingAddress() mit einem PaymentRequestDetailsUpdate-Objekt aufgelöst.
[payment handler] service-worker.js
…
// Notify the merchant of the shipping address change
details = await payment_request_event.changeShippingAddress(newAddress);
// Provided the new payment details,
// send a message back to the frontend to update the UI
postMessage('UPDATE_REQUEST', details);
break;
…
Verwenden Sie das Objekt, um die Benutzeroberfläche im Frontend zu aktualisieren. Siehe Aktualisierte Zahlungsdetails anzeigen.
Händler über eine Änderung der Versandoption informieren
Versandoptionen sind die Liefermethoden, die Händler verwenden, um gekaufte Artikel an Kunden zu versenden. Typische Versandoptionen:
- Kostenloser Versand
- Expressversand
- Internationaler Versand
- Premiumversand international
Jede Option ist mit eigenen Kosten verbunden. In der Regel sind schnellere Methoden und Optionen teurer.
Händler, die die Payment Request API verwenden, können diese Auswahl an eine Zahlungs-App delegieren. Die Zahlungs-App kann die Informationen verwenden, um eine Benutzeroberfläche zu erstellen und den Kunden eine Versandoption auswählen zu lassen.
Die Liste der Versandoptionen, die in der Payment Request API des Händlers angegeben ist, wird als Attribut von PaymentRequestEvent an den Service Worker der Zahlungs-App weitergegeben.
[merchant]
const request = new PaymentRequest([{
supportedMethods: 'https://bobbucks.dev/pay',
data: { transactionId: '****' }
}], {
displayItems: [{
label: 'Anvil L/S Crew Neck - Grey M x1',
amount: { currency: 'USD', value: '22.15' }
}],
shippingOptions: [{
id: 'standard',
label: 'Standard',
amount: { value: '0.00', currency: 'USD' },
selected: true
}, {
id: 'express',
label: 'Express',
amount: { value: '5.00', currency: 'USD' }
}],
total: {
label: 'Total due',
amount: { currency: 'USD', value : '22.15' }
}
}, { requestShipping: true });
Die Zahlungs-App kann dem Händler mitteilen, welche Versandoption der Kunde ausgewählt hat. Das ist sowohl für den Händler als auch für den Kunden wichtig, da sich durch die Änderung der Versandoption auch der Gesamtpreis ändert. Der Händler muss über den aktuellen Preis für die spätere Zahlungsbestätigung informiert werden und der Kunde muss ebenfalls über die Änderung informiert werden.
Mit der Payment Handler API kann die Zahlungs-App über den Service Worker ein Ereignis vom Typ „shippingoptionchange“ an den Händler senden. Der Service Worker sollte PaymentRequestEvent.changeShippingOption() mit der neuen Versandoptions-ID aufrufen.
[payment handler] service-worker.js
…
// Received a message from the frontend
self.addEventListener('message', async e => {
let details;
try {
switch (e.data.type) {
…
case 'SHIPPING_OPTION_CHANGED':
const newOption = e.data.shippingOptionId;
details =
await payment_request_event.changeShippingOption(newOption);
…
Der Händler erhält ein shippingoptionchange-Ereignis von der Payment Request API. Der Händler sollte die Informationen verwenden, um den Gesamtpreis zu aktualisieren, und dann mit dem aktualisierten PaymentDetailsUpdate antworten.
[merchant]
request.addEventListener('shippingoptionchange', e => {
// selected shipping option
const shippingOption = request.shippingOption;
const newTotal = {
currency: 'USD',
label: 'Total due',
value: calculateNewTotal(shippingOption),
};
// `updateWith()` sends back updated payment details
e.updateWith({ total: newTotal });
});
Wenn der Händler antwortet, wird das von PaymentRequestEvent.changeShippingOption() zurückgegebene Promise mit einem PaymentRequestDetailsUpdate-Objekt aufgelöst.
[payment handler] service-worker.js
…
// Notify the merchant of the shipping option change
details = await payment_request_event.changeShippingOption(newOption);
// Provided the new payment details,
// send a message back to the frontend to update the UI
postMessage('UPDATE_REQUEST', details);
break;
…
Verwenden Sie das Objekt, um die Benutzeroberfläche im Frontend zu aktualisieren. Siehe Aktualisierte Zahlungsdetails anzeigen.
Aktualisierte Zahlungsdetails enthalten
Sobald der Händler die Aktualisierung der Zahlungsdetails abgeschlossen hat, werden die von .changePaymentMethod(), .changeShippingAddress() und .changeShippingOption() zurückgegebenen Promises mit einem gemeinsamen PaymentRequestDetailsUpdate-Objekt aufgelöst. Der Zahlungs-Handler kann das Ergebnis verwenden, um den aktualisierten Gesamtpreis und die Versandoptionen in der Benutzeroberfläche anzuzeigen.
Händler können aus verschiedenen Gründen Fehler zurückgeben:
- Die Zahlungsmethode ist nicht zulässig.
- Die Versandadresse liegt außerhalb der unterstützten Regionen.
- Die Versandadresse enthält ungültige Informationen.
- Die Versandoption kann für die angegebene Versandadresse oder aus einem anderen Grund nicht ausgewählt werden.
Verwenden Sie die folgenden Properties, um den Fehlerstatus anzugeben:
error: Menschenlesbarer Fehlerstring. Dies ist der beste String, der Kunden angezeigt werden kann.shippingAddressErrors:AddressErrors-Objekt, das einen detaillierten Fehlerstring pro Adresseigenschaft enthält. Das ist nützlich, wenn Sie ein Formular öffnen möchten, in dem der Kunde seine Adresse bearbeiten kann, und Sie ihn direkt auf die ungültigen Felder hinweisen müssen.paymentMethodErrors: Zahlungsmethodenspezifisches Fehlerobjekt. Du kannst Händler bitten, einen strukturierten Fehler anzugeben, aber die Autoren der Web Payments-Spezifikation empfehlen, einen einfachen String zu verwenden.