PaymentRequest: Methode show()

Syntax

show()
show(details)

Parameter

details Optional

Entweder ein Objekt oder ein Promise, das zu einem Objekt aufgelöst wird. Geben Sie diesen Parameter an, wenn Ihre Architektur erfordert, dass die Details der Zahlungsanfrage zwischen der Initialisierung der Zahlungsoberfläche und dem Beginn der Benutzerinteraktion aktualisiert werden. Das Objekt sollte die aktualisierten Informationen enthalten:

displayItems Optional

Ein Array von Objekten, die jeweils einen Posten der Zahlungsanfrage beschreiben. Diese entsprechen den Posten auf einem Beleg oder einer Rechnung und haben jeweils die folgenden Eigenschaften:

amount

Ein Objekt, das den Geldwert des Postens beschreibt. Es enthält die folgenden Felder:

currency

Eine Zeichenfolge mit einem gültigen dreibuchstabigen ISO-4217-Währungscode (ISO 4217), der die für den Zahlungswert value verwendete Währung angibt.

value

Eine Zeichenfolge mit einem gültigen Dezimalwert, der den Zahlungsbetrag angibt. Sie darf nur aus einem optionalen vorangestellten „-“ für einen negativen Wert, einer oder mehreren Ziffern von 0 bis 9 und einem optionalen Dezimalpunkt („.“, unabhängig vom Gebietsschema) mit mindestens einer weiteren Ziffer bestehen. Leerzeichen sind nicht zulässig.

label

Eine Zeichenfolge mit einem für Menschen lesbaren Namen oder einer Beschreibung des berechneten Postens oder der Dienstleistung. Je nach Gestaltung der Oberfläche kann der User Agent sie dem Benutzer anzeigen.

pending

Ein boolescher Wert, der true ist, wenn der angegebene amount noch nicht endgültig feststeht. Damit können beispielsweise Versandkosten oder Steuern gekennzeichnet werden, die von der gewählten Versandadresse oder Versandoption abhängen. Der User Agent kann diese Information anzeigen, muss es aber nicht.

error Optional

Eine Zeichenfolge mit einer Fehlermeldung für den Benutzer. Wenn Sie updateWith() aufrufen und error in die aktualisierten Daten aufnehmen, zeigt der User Agent den Text als allgemeine Fehlermeldung an. Verwenden Sie für Fehler in bestimmten Adressfeldern das Feld shippingAddressErrors.

modifiers Optional

Ein Array von Objekten, die jeweils eine Anpassung für bestimmte Zahlungsmethodenkennungen beschreiben. Jedes Objekt hat die folgenden Eigenschaften:

supportedMethods

Eine Zeichenfolge, die die Zahlungsmethodenkennung darstellt. Die Anpassung gilt nur, wenn der Benutzer diese Zahlungsmethode auswählt.

total Optional

Ein Objekt, das die Eigenschaft total des Parameters detailsPromise überschreibt, wenn der Benutzer diese Zahlungsmethode auswählt. Es akzeptiert dieselben Eingaben wie die Eigenschaft total des Parameters detailsPromise.

additionalDisplayItems Optional

Ein Array von Objekten mit zusätzlichen anzuzeigenden Posten, die an die Eigenschaft displayItems des Parameters detailsPromise angehängt werden, wenn der Benutzer diese Zahlungsmethode auswählt. Diese Eigenschaft wird häufig verwendet, um einen Rabatt oder Zuschlag als Posten hinzuzufügen und so den abweichenden Gesamtbetrag für die ausgewählte Zahlungsmethode zu erklären, den der User Agent anzeigen kann. Sie akzeptiert dieselben Eingaben wie die Eigenschaft displayItems des Parameters detailsPromise.

data Optional

Ein serialisierbares Objekt mit optionalen Informationen, die von den unterstützten Zahlungsmethoden benötigt werden könnten.

Sie können eine solche Anpassung beispielsweise verwenden, um den Gesamtbetrag abhängig von der gewählten Zahlungsmethode zu ändern („5 % Rabatt bei Barzahlung!“).

shippingAddressErrors Optional

Ein Objekt mit einer Fehlermeldung für jede Eigenschaft der Versandadresse, die nicht validiert werden konnte.

shippingOptions Optional

Ein Array von Objekten, die jeweils eine verfügbare Versandoption 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 angibt. Stellen Sie sicher, dass dieser der Summe aller Posten in displayItems entspricht. Er wird nicht automatisch berechnet. Sie müssen diesen Wert jedes Mal selbst aktualisieren, wenn sich der fällige Gesamtbetrag ändert. So können Sie flexibel festlegen, wie Steuern, Rabatte und andere Anpassungen des Gesamtpreises berücksichtigt werden.

Rückgabewert

Ein Promise, das schließlich mit einer PaymentResponse erfüllt wird. Das Promise wird erfüllt, wenn der Benutzer die Zahlungsanfrage annimmt, beispielsweise indem er im Zahlungsdialog des Browsers auf eine Schaltfläche „Bezahlen“ klickt.

Ausnahmen

Die folgenden Ausnahmen können zurückgegeben werden, wenn das Promise abgelehnt wird.

AbortError DOMException

Wird zurückgegeben, wenn:

• Der Benutzer die Zahlungsanfrage abbricht.
• Der User Agent bereits einen Zahlungsdialog anzeigt. Es darf jeweils nur ein Zahlungsdialog sichtbar sein, über alle vom User Agent geladenen Dokumente hinweg.

InvalidStateError DOMException

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

NotSupportedError DOMException

Wird zurückgegeben, wenn der User Agent die beim Aufruf des Konstruktors PaymentRequest angegebenen Zahlungsmethoden nicht unterstützt.

OperationError DOMException

Wird zurückgegeben, um einen internen Fehler in der zugrunde liegenden App anzuzeigen, die die Zahlung verarbeitet.

SecurityError DOMException

Wird zurückgegeben, wenn show() nicht als Reaktion auf eine Benutzeraktion aufgerufen wurde, etwa auf ein click- oder keyup-Ereignis. Ob ein SecurityError aus weiteren Gründen ausgelöst wird, liegt im Ermessen des User Agents. Dazu kann gehören, dass show() innerhalb kurzer Zeit zu oft aufgerufen wird oder dass ein Aufruf erfolgt, während Zahlungsanfragen durch eine Kindersicherung blockiert sind.

Sicherheit

Eine vorübergehende Benutzeraktivierung ist erforderlich. Damit diese Funktion verwendet werden kann, muss der Benutzer mit der Seite oder einem Element der Benutzeroberfläche interagieren.

Hinweise zur Verwendung

Die gebräuchlichsten Muster für die Verwendung von show() sind die Syntax async/await oder show().then().catch(), um die Antwort und eine mögliche Ablehnung zu verarbeiten. Sie sehen wie folgt aus:

async/await-Syntax

Wenn Sie mit await auf die Erfüllung eines Promise warten, lässt sich der Code zur Verarbeitung von Zahlungen besonders übersichtlich 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 prüfen die Methoden checkAddress() und checkShipping() die Änderungen der Versandadresse beziehungsweise der Versandoption. Als Antwort liefern sie entweder ein Objekt oder ein Promise, das ein solches Objekt zurückgibt. Dieses Objekt enthält die Felder der PaymentResponse, die geändert wurden oder geändert werden müssen.

Die unten stehende Methode validateResponse() wird aufgerufen, sobald show() zurückkehrt. Sie prüft die zurückgegebene response und übermittelt entweder die Zahlung oder lehnt sie als fehlgeschlagen ab:

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 prüft eine benutzerdefinierte Funktion namens checkAllValues() jeden Wert in der response auf Gültigkeit. Sie gibt true zurück, wenn alle Felder gültig sind, und andernfalls false. Nur wenn alle Felder gültig sind, wird die Methode complete() für die Antwort mit der Zeichenfolge "success" aufgerufen. Dies gibt an, dass alles gültig ist und die Zahlung entsprechend abgeschlossen werden kann.

Wenn Felder unzulässige Werte enthalten oder der vorangehende Code eine Ausnahme auslöst, wird complete() mit der Zeichenfolge "fail" aufgerufen. Dies gibt an, dass der Zahlungsvorgang abgeschlossen und fehlgeschlagen ist.

Statt die Zahlung sofort als fehlgeschlagen zu behandeln, können Sie retry() für das Antwortobjekt aufrufen, um den User Agent zu einem erneuten Verarbeitungsversuch aufzufordern. Dies sollte in der Regel erst geschehen, nachdem der Benutzer alle erforderlichen Korrekturen an der Bestellung vorgenommen hat.

Um den Zahlungsvorgang zu starten, genügt schließlich ein Aufruf der Methode processPayment().

then/catch-Syntax

Sie können Zahlungen auch mit dem älteren Promise-basierten Ansatz verarbeiten. Verwenden Sie dazu die Funktionen then() und catch() für das von show() zurückgegebene Promise:

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 gleichwertig mit der Methode processPayment() unter Verwendung der await-Syntax.

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

checkAllValues() könnte sogar eine synchrone Funktion sein. Das kann allerdings unerwünschte Auswirkungen auf die Leistung haben:

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

Weitere Informationen zur Arbeit mit Promises finden Sie im Artikel Promises verwenden.

Beispiele

Im folgenden Beispiel wird ein PaymentRequest-Objekt initialisiert, bevor die Methode show() aufgerufen wird. Die Methode startet den integrierten Vorgang des User Agents, um Zahlungsinformationen vom Benutzer abzurufen. show() gibt ein Promise zurück, das mit einem PaymentResponse-Objekt erfüllt wird, sobald die Benutzerinteraktion abgeschlossen ist. Anschließend verwendet der Entwickler 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 angeben kann.

button.onclick = async () => {
  // 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 Sie den Zahlungsdialog während seiner Anzeige für den Benutzer aktualisieren können.

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;

Spezifikationen

Browser-Kompatibilität

Siehe auch

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