Diese Seite wurde von der Cloud Translation API übersetzt.

Umgang mit optionalen Zahlungsinformationen mit einem Service Worker

So passen Sie Ihre webbasierte Zahlungs-App an Webzahlungen an und bieten Kunden eine bessere Nutzererfahrung.

Eiji Kitamura

Sobald eine webbasierte Zahlungs-App eine Zahlungsanforderung empfängt und eine Zahlungstransaktion initiiert, fungiert der Service Worker als Kommunikationsknoten zwischen dem Händler und der Zahlungs-App. In diesem Beitrag wird erläutert, wie eine Zahlungs-App über einen Service Worker Informationen zur Zahlungsmethode, Versandadresse oder Kontaktdaten an den Händler weitergeben kann.

Optionale Zahlungsinformationen mit einem Service Worker verarbeiten

Händler über eine Änderung der Zahlungsmethode informieren

Zahlungs-Apps können mehrere Zahlungsinstrumente mit verschiedenen Zahlungsmethoden unterstützen.

Kunde	Zahlungsmethode	Zahlungsmittel
A	Kreditkartenaussteller 1	`****1234`
	Kreditkartenaussteller 1	`****4242`
	Bank X	`******123`
B	Kreditkartenaussteller 2	`****5678`
B	Bank X	`******456`

In der obigen Tabelle sind beispielsweise für den Web-basierten 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 der Kunde über die Zahlungs-App eines der Zahlungsmittel auswählen und damit für den Händler bezahlen.

Benutzeroberfläche für die 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 beispielsweise nützlich, wenn der Händler eine Rabattkampagne für eine bestimmte Zahlungsmethode schalten möchte.

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

Händler über eine Änderung der Zahlungsmethode informieren

Zahlungs-Apps können ein methodDetails-Objekt als optionales zweites Argument für PaymentRequestEvent.changePaymentMethod() übergeben. Dieses Objekt kann beliebige Zahlungsmethodedetails enthalten, die der Händler zum Verarbeiten 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 zurückgegebene Promise PaymentRequestEvent.changePaymentMethod() 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 auf dem Front-End zu aktualisieren. Weitere Informationen finden Sie unter Aktualisierte Zahlungsdetails berücksichtigen.

Händler über eine Ä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 hilfreich, da sie die Adresserfassung an Zahlungs-Apps delegieren können. Da die Adressdaten im Standarddatenformat bereitgestellt werden, kann der Händler davon ausgehen, dass er Versandadressen in einer einheitlichen Struktur erhält.

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

Benutzeroberfläche zur Auswahl der Versandadresse — UI für die Auswahl der Lieferadresse

Zahlungs-Apps können eine Benutzeroberfläche bereitstellen, über die eine Versandadresse bearbeitet oder zuvor registrierte 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 regionale Versandbeschränkung für den Artikel erfüllt (z. B. nur im Inland).
Händler können die Liste der Versandoptionen je nach Region der Versandadresse ändern (z. B. „Internationaler regulärer Versand“ oder „Expressversand“).
Ein Händler kann die neuen Versandkosten basierend auf der Adresse anwenden und den Gesamtpreis aktualisieren.

Mit der Payment Handler API kann die Zahlungs-App dem Händler über den Service Worker ein Ereignis vom Typ „Lieferadresse geändert“ senden, um ihn über die neue Lieferadresse zu informieren. Der Dienst-Worker sollte PaymentRequestEvent.changeShippingAddress() mit dem Objekt „new address“ aufrufen.

Händler über eine Änderung der Versandadresse informieren

[Zahlungs-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 : Entfernte Adresse. In diesem Fall ist es nicht erforderlich, dem Händler die vollständige Versandadresse mitzuteilen, da dies ein Risiko für den Datenschutz der Kunden darstellt. Der Händler erhält nur die Teile der Adresse, die er zur Bestimmung der Versandkosten benötigt. Insbesondere werden die Felder organization, phone, recipient und addressLine aus der von der Zahlungs-App bereitgestellten Adresse gelöscht, 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.

[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. Weitere Informationen finden Sie unter Aktualisierte Zahlungsdetails berücksichtigen.

Händler über eine Änderung der Versandoption informieren

Versandoptionen sind die Liefermethoden, mit denen Händler gekaufte Artikel an einen Kunden versenden. Gängige Versandoptionen:

Kostenloser Versand
Expressversand
Internationaler Versand
Premiumversand (international)

Jedes ist mit eigenen Kosten verbunden. In der Regel sind schnellere Methoden/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 dem Kunden die Auswahl einer Versandoption zu ermöglichen.

Benutzeroberfläche zur Auswahl der Versandoption — UI für die Auswahl der Versandoptionen

Die Liste der Versandoptionen, die in der Payment Request API des Händlers angegeben ist, wird als Property von PaymentRequestEvent an den Service Worker der Zahlungs-App 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 durch die Änderung der Versandoption auch der Gesamtpreis ändert. Der Händler muss später über den aktuellen Preis für die Zahlungsüberprüfung informiert werden. Außerdem muss der Kunde über die Änderung informiert werden.

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

Händler über eine Ä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 ein shippingoptionchange-Ereignis von der Payment Request API. Der Händler sollte die Informationen verwenden, um den Gesamtpreis zu aktualisieren, und dann mit der 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 zurückgegebene Promise PaymentRequestEvent.changeShippingOption() 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. Weitere Informationen finden Sie unter Aktualisierte Zahlungsdetails berücksichtigen.

Aktualisierte Zahlungsdetails

Sobald der Händler die Zahlungsdetails aktualisiert hat, werden die Versprechen, die von .changePaymentMethod(), .changeShippingAddress() und .changeShippingOption() zurückgegeben wurden, mit einem gemeinsamen PaymentRequestDetailsUpdate-Objekt aufgelöst. Der Zahlungsabwickler kann das Ergebnis verwenden, um den aktualisierten Gesamtpreis und die Versandoptionen auf der Benutzeroberfläche anzuzeigen.

Hinweis: Das PaymentRequestDetailsUpdate-Objekt wird vom Händler übergeben und enthält genau die Informationen, die der Händler über die Payment Request API in das PaymentDetailsUpdate-Objekt eingegeben hat. Die beste Möglichkeit, dafür zu sorgen, dass Händler Ihnen die erwarteten Informationen zur Verfügung stellen, ist eine gute Entwicklerdokumentation oder eine JavaScript-Bibliothek zur Steuerung der Informationen oder beides.

Händler können aus verschiedenen Gründen Fehler zurückgeben:

Die Zahlungsmethode ist nicht zulässig.
Die Versandadresse befindet sich außerhalb der unterstützten Regionen.
Die Versandadresse enthält ungültige Informationen.
Die Versandoption kann aus einem anderen Grund oder für die angegebene Lieferadresse nicht ausgewählt werden.

Verwenden Sie die folgenden Properties, um den Fehlerstatus anzugeben:

error: Ein für Menschen lesbarer Fehlerstring. Dieser String sollte Kunden angezeigt werden.
shippingAddressErrors: AddressErrors-Objekt, das einen detaillierten Fehlerstring pro Adressattribut enthält. Das ist nützlich, wenn Sie ein Formular öffnen möchten, in dem der Kunde seine Adresse bearbeiten kann, und ihn direkt auf die ungültigen Felder hinweisen müssen.
paymentMethodErrors: Zahlungsmittelspezifisches Fehlerobjekt. Sie können Händler bitten, einen strukturierten Fehler anzugeben. Die Autoren der Web Payments-Spezifikation empfehlen jedoch, 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

[payment handler] frontend

So kannst du es ausprobieren:

Rufen Sie https://paymentrequest-demo.glitch.me/ auf.
Sehen Sie sich den Bereich ganz unten auf der Seite an.
Drücken Sie auf die Schaltfläche Zahlungsmethode hinzufügen.
Geben Sie https://paymenthandler-demo.glitch.me in das Feld ID der Zahlungsmethode ein.
Drücken Sie neben dem Feld auf die Schaltfläche Bezahlen.