PaymentRequest: show() Methode

details Optional

Entweder ein Objekt oder ein Promise, das in ein Objekt aufgelöst wird. Geben Sie dies an, wenn Ihre Architektur erfordert, dass die Details der Zahlungsanforderung zwischen der Instanziierung der Zahlungsoberfläche und dem Beginn der Benutzerinteraktion aktualisiert werden müssen. Das Objekt sollte die aktualisierten Informationen enthalten:

displayItems Optional

Ein Array von Objekten, die jeweils einen Posten für die Zahlungsanforderung beschreiben. Diese repräsentieren die Posten auf einem Beleg oder Rechnung, jeweils mit folgenden Eigenschaften:

amount

Ein Objekt, das den Geldwert des Artikels beschreibt. Dieses Objekt beinhaltet folgende Felder:

currency

Ein String, der einen gültigen 3-Buchstaben- ISO 4217 Währungsidentifikator enthält (ISO 4217), der die für die Zahlung verwendete Währung angibt.

value

Ein String, der einen gültigen Dezimalwert darstellt, der den Betrag der Währung, die die Zahlungssumme bildet, beinhaltet. Dieser String darf nur ein optionales führendes "-" enthalten, um einen negativen Wert anzugeben, dann eine oder mehrere Ziffern von 0 bis 9, und ein optionaler Dezimalpunkt (".", unabhängig von der Sprache) gefolgt von mindestens einer weiteren Ziffer. Keine Leerzeichen sind erlaubt.

label

Ein String, der einen menschenlesbaren Namen oder eine Beschreibung des Artikels oder der Dienstleistung angibt, für den/die berechnet wird. Dies kann dem Benutzer vom User-Agent angezeigt werden, je nach Gestaltung der Oberfläche.

pending

Ein boolescher Wert, der true ist, wenn der angegebene amount noch nicht endgültig ist. Dies kann verwendet werden, um Posten wie Liefer- oder Steuerbeträge zu zeigen, die von der Auswahl der Lieferadresse, der Lieferoption oder Ähnlichem abhängen. Der User-Agent kann diese Informationen anzeigen, ist jedoch nicht dazu verpflichtet.

error Optional Veraltet Nicht standardisiert

Ein String, der eine Fehlermeldung angibt, die dem Benutzer angezeigt werden soll. Wenn updateWith()](/de/docs/Web/API/PaymentRequestUpdateEvent/updateWith) aufgerufen wird und error in den aktualisierten Daten enthalten ist, zeigt der User-Agent den Text als allgemeine Fehlermeldung an. Für feldspezifische Adressfehler verwenden Sie das Feld shippingAddressErrors.

modifiers Optional

Ein Array von Objekten, die jeweils einen Modifikator für bestimmte Zahlungsmethoden-Identifikatoren beschreiben, jeweils mit folgenden Eigenschaften:

supportedMethods

Ein String, der den Zahlungsmodifikator-Identifikator repräsentiert. Der Zahlungsmodifikator-Identifikator gilt nur, wenn der Benutzer diese Zahlungsmethode auswählt.

total Optional

Ein Objekt, das die total-Eigenschaft des detailsPromise-Parameters überschreibt, wenn diese Zahlungsmethode vom Benutzer ausgewählt wird. Die Eigenschaft nimmt dieselben Eingaben wie die total-Eigenschaft des detailsPromise-Parameters.

additionalDisplayItems Optional

Ein Array von Objekten, die zusätzliche Anzeigeartikel bereitstellen, die der displayItems-Eigenschaft des detailsPromise-Parameters hinzugefügt werden, wenn diese Zahlungsmethode vom Benutzer ausgewählt wird. Diese Eigenschaft wird häufig verwendet, um eine Rabatt- oder Aufschlagszeile hinzuzufügen, die den Grund für den unterschiedlichen Gesamtbetrag für die ausgewählte Zahlungsmethode angibt, den der User-Agent anzeigen kann. Die Eigenschaft nimmt dieselben Eingaben wie die displayItems-Eigenschaft des detailsPromise-Parameters.

data Optional

Ein serialisierbares Objekt, das optionale Informationen bereitstellt, die von den unterstützten Zahlungsmethoden benötigt werden könnten.

Zum Beispiel könnte man einen verwenden, um den Gesamtzahlungsbetrag basierend auf der ausgewählten Zahlungsmethode anzupassen ("5% Rabatt bei Barzahlung!").

shippingAddressErrors Optional Veraltet Nicht standardisiert

Ein Objekt, das eine Fehlermeldung für jede Eigenschaft der Lieferadresse enthält, die nicht validiert werden konnte.

shippingOptions Optional Veraltet Nicht standardisiert

Ein Array von Objekten, die jeweils eine verfügbare Lieferoption beschreiben, aus denen der Benutzer wählen kann.

total Optional

Ein Objekt mit denselben Eigenschaften wie die Objekte in displayItems, das einen aktualisierten Gesamtbetrag für die Zahlung bereitstellt. Stellen Sie sicher, dass dieser der Summe aller Artikel in displayItems entspricht. Dies wird nicht automatisch berechnet. Sie müssen diesen Wert selbst aktualisieren, wann immer sich der Gesamtbetrag ändert. Dies gibt Ihnen die Flexibilität, wie Sie mit Steuern, Rabatten und anderen Anpassungen des Gesamtpreises verfahren.

Ein Promise, das schließlich mit einem PaymentResponse aufgelöst wird. Das Versprechen wird aufgelöst, wenn der Benutzer die Zahlungsanforderung akzeptiert (z.B. durch Klicken auf eine "Bezahlen"-Schaltfläche im Zahlungsblatt des Browsers).

Ausnahmen werden zurückgegeben, wenn das Promise zurückgewiesen wird.

AbortError DOMException

Wird zurückgegeben, wenn der User-Agent bereits ein Zahlungsfenster anzeigt. Es darf jeweils nur ein Zahlungsfenster sichtbar sein über alle vom User-Agent geladenen Dokumente.

Das Versprechen wird auch mit AbortError zurückgewiesen, wenn der Benutzer die Zahlungsanforderung abbricht.

InvalidStateError DOMException

Wird zurückgegeben, wenn dieselbe Zahlung bereits für diese Anfrage angezeigt wurde (ihr Zustand ist interactive, da sie bereits angezeigt wird).

NotSupportedError DOMException

Wird zurückgegeben, wenn der User-Agent die bei der Erstellung der PaymentRequest angegebene Zahlungsmethode nicht unterstützt.

SecurityError DOMException

Wird zurückgegeben, wenn der Aufruf von show() nicht als Reaktion auf eine Benutzeraktion erfolgt, wie ein click oder ein keyup-Ereignis. Andere Gründe, warum ein SecurityError ausgelöst werden könnte, liegen im Ermessen des User-Agents und können Situationen wie zu viele Aufrufe von show() in kurzer Zeit oder show()-Aufrufe umfassen, wenn Zahlungsanforderungen durch Kindersicherungen blockiert werden.

Transiente Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.

Die gebräuchlichsten Muster zur Verwendung von show() umfassen entweder die async/await-Syntax oder die Verwendung von show().then().catch(), um die Antwort und mögliche Zurückweisungen zu verarbeiten. Diese sehen so aus:

Die Verwendung von await, um darauf zu warten, dass ein Versprechen aufgelöst wird, ermöglicht es, den Code zur Bearbeitung von Zahlungen besonders klar zu schreiben:

async function processPayment() {
  try {
    const payRequest = new PaymentRequest(methodData, details, options);

    payRequest.onshippingaddresschange = (ev) =>
      ev.updateWith(checkAddress(payRequest));
    payRequest.onshippingoptionchange = (ev) =>
      ev.updateWith(checkShipping(payRequest));

    const response = await payRequest.show();
    await validateResponse(response);
  } catch (err) {
    /* handle the error; AbortError usually means a user cancellation */
  }
}

In diesem Code überprüfen die Methoden checkAddress() und checkShipping() jeweils die Änderungen an der Lieferadresse und der Lieferoption und geben als Antwort entweder ein Objekt oder ein Versprechen zurück, das eines zurückgibt; dieses Objekt enthält die Felder in der PaymentResponse, die geändert wurden oder geändert werden müssen.

Die validateResponse()-Methode wird aufgerufen, wenn show() zurückkehrt, um die zurückgegebene response zu prüfen und entweder die Zahlung zu übermitteln oder die Zahlung als fehlgeschlagen abzulehnen:

async function validateResponse(response) {
  try {
    if (await checkAllValues(response)) {
      await response.complete("success");
    } else {
      await response.complete("fail");
    }
  } catch (err) {
    await response.complete("fail");
  }
}

Hier überprüft eine benutzerdefinierte Funktion namens checkAllValues() jeden Wert in der response und stellt sicher, dass sie gültig sind, und gibt true zurück, wenn alle Felder gültig sind, oder false, wenn eines nicht ist. Nur wenn alle Felder gültig sind, wird die Methode complete() mit dem String "success" aufgerufen, was angibt, dass alles gültig ist und die Zahlung entsprechend abgeschlossen werden kann.

Wenn Felder unakzeptable Werte haben oder wenn der vorherige Code eine Ausnahme wirft, wird complete() mit dem String "fail" aufgerufen, was darauf hinweist, dass der Zahlungsvorgang abgeschlossen und fehlgeschlagen ist.

Anstatt sofort zu scheitern, könnten Sie sich entscheiden, retry() für das Antwortobjekt aufzurufen, um den Benutzer-Agent zu bitten, die Zahlung erneut zu versuchen; dies sollte normalerweise nur erfolgen, nachdem der Benutzer alle notwendigen Korrekturen an der Bestellung vorgenommen hat.

Den Zahlungsvorgang zu starten, ist schließlich so einfach wie den Aufruf der processPayment()-Methode.

Sie können auch den älteren, auf Versprechen basierenden Ansatz verwenden, um mit Zahlungen zu arbeiten, indem Sie die then()- und catch()-Funktionen für das Versprechen verwenden, das von show() zurückgegeben wird:

function processPayment() {
  const payRequest = new PaymentRequest(methodData, details, options);

  payRequest.onshippingaddresschange = (ev) =>
    ev.updateWith(checkAddress(payRequest));
  payRequest.onshippingoptionchange = (ev) =>
    ev.updateWith(checkShipping(payRequest));

  payRequest
    .show()
    .then((response) => validateResponse(response))
    .catch((err) => handleError(err));
}

Dies ist funktional äquivalent zur processPayment()-Methode, die die await-Syntax verwendet.

function validateResponse(response) {
  checkAllValues(response)
    .then((response) => response.complete("success"))
    .catch((response) => response.complete("fail"));
}

Sie könnten sogar checkAllValues() als synchrone Funktion haben, obwohl das möglicherweise unerwünschte Leistungsimplikationen hat:

function validateResponse(response) {
  if (checkAllValues(response)) {
    response.complete("success");
  } else {
    response.complete("fail");
  }
}

Lesen Sie den Artikel Verwendung von Promises für weitere Informationen, falls Sie mehr darüber erfahren möchten, wie Sie mit Versprechen arbeiten.

Im folgenden Beispiel wird ein PaymentRequest-Objekt instanziiert, bevor die show()-Methode aufgerufen wird. Diese Methode löst den eingebauten Prozess des User-Agents aus, um Zahlungsinformationen vom Benutzer abzurufen. Die show()-Methode gibt ein Promise zurück, das in ein PaymentResponse-Objekt aufgelöst wird, wenn die Benutzerinteraktion abgeschlossen ist. Der Entwickler verwendet dann die Informationen im PaymentResponse-Objekt, um die Zahlungsdaten zu formatieren und an den Server zu senden. Sie sollten die Zahlungsinformationen asynchron an den Server senden, damit der abschließende Aufruf von paymentResponse.complete() den Erfolg oder Misserfolg der Zahlung anzeigen kann.

button.onclick = async function handlePurchase() {
  // Initialization of PaymentRequest arguments are excerpted for the sake of
  // brevity.
  const payment = new PaymentRequest(methods, details, options);
  try {
    const response = await payment.show();
    // Process response here, including sending payment instrument
    // (e.g., credit card) information to the server.
    // paymentResponse.methodName contains the selected payment method
    // paymentResponse.details contains a payment method specific response
    await response.complete("success");
  } catch (err) {
    console.error("Uh oh, something bad happened", err.message);
  }
};

Das folgende Beispiel zeigt, wie das Zahlungsformular aktualisiert wird, während es dem Endbenutzer präsentiert wird.

async function requestPayment() {
  // We start with AU$0 as the total.
  const initialDetails = {
    total: {
      label: "Total",
      amount: { value: "0", currency: "AUD" },
    },
  };
  const request = new PaymentRequest(methods, initialDetails, options);
  // Check if the user supports the `methods`
  if (!(await request.canMakePayment())) {
    return; // no, so use a web form instead.
  }
  // Let's update the total as the sheet is shown
  const updatedDetails = {
    total: {
      label: "Total",
      amount: { value: "20", currency: "AUD" },
    },
  };
  const response = await request.show(updatedDetails);
  // Check response, etc.
}

document.getElementById("buyButton").onclick = requestPayment;

• Payment Request API
• Verwendung der Payment Request API
• PaymentRequest.abort()
• PaymentResponse
• PaymentResponse.retry()
• PaymentResponse.complete()