Umgang mit optionalen Zahlungsinformationen mit einem Service Worker

Hier erfahren Sie, wie Sie Ihre webbasierte Zahlungs-App an Web Payments anpassen und die Nutzerfreundlichkeit für Ihre Kunden verbessern.

Eiji Kitamura

Warnung : Die Unterstützung für Versand- und Adressen in der Payment Request API wurde einst aus der Spezifikation und aus Chrome entfernt, wird aber in der Spezifikation zurückgesetzt. Aus diesem Grund haben wir auch die Dokumentation zu Versand und Adresse zurückgesetzt.

Wenn eine webbasierte Zahlungs-App eine Zahlungsanforderung 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, Versandadresse oder Kontaktdaten an den Händler weitergeben kann.

Umgang mit optionalen Zahlungsinformationen mit einem Service Worker

Händler über eine Änderung der Zahlungsmethode informieren

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 für die webbasierte Wallet von Kunde A beispielsweise 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 der Kunde in der Zahlungs-App eines der Zahlungsmittel auswählen und damit für den Händler bezahlen.

Benutzeroberfläche zur Auswahl der Zahlungsmethode

Die Zahlungs-App kann dem Händler mitteilen, welche Zahlungsmethode der Kunde ausgewählt hat, bevor die vollständige Zahlungsantwort gesendet wird. Das ist nützlich, wenn der Händler z. B. eine Rabattkampagne für eine bestimmte Zahlungsmethode durchführen möchte.

Mit der Payment Handler API kann die Zahlungs-App über einen Service Worker ein Ereignis vom Typ „Änderung der Zahlungsmethode“ an den Händler senden, um die neue ID der Zahlungsmethode zu benachrichtigen. Der Service Worker sollte PaymentRequestEvent.changePaymentMethod() mit den neuen Informationen zur Zahlungsmethode aufrufen.

Händler über Änderung der Zahlungsmethode informieren

Zahlungs-Apps können ein methodDetails-Objekt als optionales zweites Argument für PaymentRequestEvent.changePaymentMethod() übergeben. Dieses Objekt kann Details zu beliebigen Zahlungsmethoden enthalten, die der Händler benötigt, um das Änderungsereignis zu verarbeiten.

Warnung : Wenn Sie dem Händler detaillierte Informationen über einen Kunden mitteilen, bevor die Transaktion abgeschlossen wird, stellt dies ein potenzielles Datenschutzrisiko dar. Als Best Practice sollten Zahlungs-Apps unnötige Details so weit wie möglich weglassen.

[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.

[Händler]

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 Versprechen, dass PaymentRequestEvent.changePaymentMethod() zurückgegeben wurde, 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 UI im Front-End zu aktualisieren. Siehe Aktualisierte Zahlungsdetails anzeigen.

Händler über die Änderung der Versandadresse informieren

Zahlungs-Apps können die Versandadresse eines Kunden im Rahmen einer Zahlungstransaktion an den Händler weitergeben.

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 Versandadressen in einer einheitlichen Struktur erhalten.

Außerdem können Kunden ihre Adressinformationen bei ihrer bevorzugten Zahlungs-App registrieren und sie für verschiedene Händler verwenden.

Benutzeroberfläche zur Auswahl der Versandadresse

Zahlungs-Apps können eine UI zur Verfügung stellen, über die eine Versandadresse bearbeitet oder vorregistrierte Adressinformationen für den Kunden bei einer Zahlungstransaktion ausgewählt werden können. Wenn eine Versandadresse vorübergehend ermittelt wird, kann die Zahlungs-App den Händler über die entfernten 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 im Inland).
• Ein Händler kann die Liste der Versandoptionen basierend auf der Region der Versandadresse ändern (z. B. Internationaler Standard oder Express).
• Ein Händler kann die neuen Versandkosten anhand der Adresse anwenden und den Gesamtpreis aktualisieren.

Mit der Payment Handler API kann die Zahlungs-App ein Ereignis vom Typ „Änderung der Versandadresse“ vom Service Worker an den Händler senden, um die neue Versandadresse zu benachrichtigen. Der Service Worker sollte PaymentRequestEvent.changeShippingAddress() mit dem neuen Adressobjekt aufrufen.

Händler über die Änderung der Versandadresse informieren

[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);
      …

Wichtiger Begriff : Adresse, die entfernt wurde. Es ist in diesem Fall nicht erforderlich, dem Händler die vollständige Versandadresse mitzuteilen. Dies ist ein Risiko für den Datenschutz des Kunden. Der Händler erhält nur die Teile der Adresse, die er zur Bestimmung der Versandkosten benötigt. Insbesondere löscht der Browser die Felder organization, phone, recipient und addressLine aus der von der Zahlungs-App angegebenen Adresse, bevor das Ereignis shippingaddresschange im DOM des Händlers ausgelöst wird.

Der Händler erhält ein shippingaddresschange-Ereignis von der Payment Request API, damit er mit der aktualisierten PaymentDetailsUpdate antworten kann.

[Händler]

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 UI im Front-End zu aktualisieren. Siehe Aktualisierte Zahlungsdetails anzeigen.

Händler über die Änderung der Versandoption informieren

Versandoptionen sind Versandmethoden, mit denen Händler gekaufte Artikel an einen Kunden versenden. Typische Versandoptionen:

• Kostenloser Versand
• Expressversand
• Internationaler Versand
• Internationaler Premiumversand

Für jede Option fallen eigene Kosten an. Schnellere Methoden/Optionen sind in der Regel teurer.

Händler, die die Payment Request API verwenden, können diese Auswahl an eine Zahlungs-App delegieren. Die Zahlungs-App kann anhand der Informationen eine Benutzeroberfläche erstellen und dem Kunden die Auswahl einer Versandoption überlassen.

Benutzeroberfläche zur Auswahl der Versandoption

Die Liste der in der Payment Request API des Händlers angegebenen Versandoptionen wird an den Service Worker der Zahlungs-App als Eigenschaft von PaymentRequestEvent weitergegeben.

[Händler]

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 bei einer Änderung der Versandoption auch der Gesamtpreis ändert. Der Händler muss später über den aktuellen Preis für die Zahlungsbestätigung informiert werden und auch der Kunde muss über die Änderung informiert sein.

Mit der Payment Handler API kann die Zahlungs-App ein Ereignis vom Typ „Änderung der Versandoption“ vom Service Worker an den Händler senden. Der Service Worker sollte PaymentRequestEvent.changeShippingOption() mit der neuen ID der Versandoption aufrufen.

Händler über die Änderung der Versandoption informieren

[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 von der Payment Request API ein shippingoptionchange-Ereignis. Der Händler sollte anhand der Informationen den Gesamtpreis aktualisieren und dann mit dem aktualisierten PaymentDetailsUpdate antworten.

[Händler]

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 Versprechen, dass PaymentRequestEvent.changeShippingOption() zurückgegeben wurde, 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 UI im Front-End zu aktualisieren. Siehe Aktualisierte Zahlungsdetails anzeigen.

Aktualisierte Zahlungsdetails anzeigen

Sobald der Händler die Aktualisierung der Zahlungsdetails abgeschlossen hat, werden die von .changePaymentMethod(), .changeShippingAddress() und .changeShippingOption() zurückgegebenen Promise mit einem gemeinsamen PaymentRequestDetailsUpdate-Objekt aufgelöst. Der Zahlungs-Handler kann das Ergebnis verwenden, um den aktualisierten Gesamtpreis und Versandoptionen an die Benutzeroberfläche anzuzeigen.

Hinweis : Das PaymentRequestDetailsUpdate-Objekt wird vom Händler übergeben und enthält die genauen Informationen, die der Händler über die Payment Request API im PaymentDetailsUpdate-Objekt eingegeben hat. Am besten stellen Sie sicher, dass Händler Ihnen die von Ihnen erwarteten Informationen liefern, indem Sie eine gute Entwicklerdokumentation und/oder eine JavaScript-Bibliothek zur Kontrolle der Informationen zur Verfügung stellen.

Fehler können aus verschiedenen Gründen von Händlern zurückgegeben werden:

• Die Zahlungsmethode wird nicht akzeptiert.
• 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 einen anderen Grund nicht ausgewählt werden.

Verwenden Sie die folgenden Attribute, um den Fehlerstatus widerzuspiegeln:

• error: menschenlesbarer Fehlerstring. Dies ist die beste Zeichenfolge, die Kunden angezeigt werden sollte.
• shippingAddressErrors: AddressErrors-Objekt, das einen detaillierten Fehlerstring pro Adressattribut enthält. Das ist hilfreich, wenn Sie ein Formular öffnen möchten, in dem der Kunde seine Adresse bearbeiten kann, und Sie ihn direkt auf die ungültigen Felder verweisen müssen.
• paymentMethodErrors: Fehlerobjekt, das für die jeweilige Zahlungsmethode spezifisch ist Du kannst Händler bitten, einen strukturierten Fehler anzugeben, aber die Autoren der Web Payments-Spezifikation empfehlen, einen einfachen String zu verwenden.

Beispielcode

Die meisten Beispielcodes, die Sie in diesem Dokument gesehen haben, waren Auszüge aus der folgenden funktionierenden Beispiel-App:

https://paymenthandler-demo.glitch.me

[payment-Handler]-Service-Worker

[Zahlungs-Handler] Frontend

So probierst du es aus:

1. Rufen Sie https://paymentrequest-demo.glitch.me/ auf.
2. Sehen Sie sich den Bereich ganz unten auf der Seite an.
3. Klicken Sie auf Zahlungsschaltfläche hinzufügen.
4. Geben Sie in das Feld ID der Zahlungsmethode https://paymenthandler-demo.glitch.me ein.
5. Drücke auf die Schaltfläche Bezahlen, die neben dem Feld angezeigt wird.