PaymentRequest: show()-Methode

Syntax

show()
show(details)

Parameter

details Optional

Entweder ein Objekt oder ein Promise, das zu einem Objekt aufgelöst wird. Geben Sie dies an, falls Ihre Architektur erfordert, dass die Zahlungsanforderungsdetails zwischen dem Instanziieren der Zahlungsoberfläche und dem Beginn der Interaktion des Nutzers aktualisiert werden müssen. Das Objekt sollte die aktualisierten Informationen enthalten:

displayItems Optional

Ein Array von Objekten, die jeweils ein Zeilenobjekt für die Zahlungsanforderung beschreiben. Diese repräsentieren die Zeilenobjekte auf einer Quittung oder Rechnung, jeweils mit den folgenden Eigenschaften:

amount

Ein Objekt, das den Geldwert des Artikels beschreibt. Dieses Objekt umfasst die folgenden Felder:

currency

Eine Zeichenfolge mit einem gültigen dreistelligen ISO 4217-Währungskennzeichen (ISO 4217), das die für den Zahlungswert verwendete Währung angibt.

value

Eine Zeichenfolge mit einem gültigen Dezimalwert, der die Mengenangabe der Währung darstellt, die den Zahlungsbetrag ausmacht. Diese Zeichenfolge darf nur optional ein führendes "-" enthalten, um einen negativen Wert anzuzeigen, gefolgt von einer oder mehreren Ziffern von 0 bis 9, und einem optionalen Dezimalpunkt (".", unabhängig von der Spracheinstellung), gefolgt von mindestens einer weiteren Ziffer. Kein Leerraum ist erlaubt.

label

Eine Zeichenfolge, die einen menschenlesbaren Namen oder eine Beschreibung des Artikels oder der Dienstleistung spezifiziert, für die eine Gebühr erhoben wird. Dies kann dem Benutzer durch den Benutzeragenten angezeigt werden, je nach Design der Schnittstelle.

pending

Ein boolescher Wert, der true ist, wenn der angegebene amount noch nicht finalisiert wurde. Dies kann verwendet werden, um Elemente wie Versandkosten oder Steuerbeträge anzuzeigen, die von der Auswahl der Versandadresse, der Versandoption oder Ähnlichem abhängen. Der Benutzeragent kann diese Informationen anzeigen, muss es aber nicht.

error Optional Veraltet Nicht standardisiert

Eine Zeichenfolge, die eine Fehlermeldung angibt, die dem Benutzer angezeigt werden soll. Beim Aufruf von updateWith() führt die Einbeziehung von error in die aktualisierten Daten dazu, dass der Benutzeragent den Text als allgemeine Fehlermeldung anzeigt. Für feldspezifische Adressfehler verwenden Sie das Feld shippingAddressErrors.

modifiers Optional

Ein Array von Objekten, die jeweils einen Modifikator für bestimmte Zahlungsmethodenkennzeichen beschreiben, jeweils mit den folgenden Eigenschaften:

supportedMethods

Eine Zeichenfolge, die das Zahlungsmethodenkennzeichen darstellt. Das Zahlungsmethodenkennzeichen gilt nur, wenn der Benutzer diese Zahlungsmethode auswählt.

total Optional

Ein Objekt, das die Eigenschaft total des Parameters detailsPromise überschreibt, falls diese Zahlungsmethode vom Benutzer ausgewählt wird. Die Eigenschaft nimmt denselben Eingabewert wie die Eigenschaft total des Parameters detailsPromise.

additionalDisplayItems Optional

Ein Array von Objekten bietet zusätzliche Anzeigeelemente, die der Eigenschaft displayItems des Parameters detailsPromise hinzugefügt werden, falls diese Zahlungsmethode vom Benutzer ausgewählt wird. Diese Eigenschaft wird häufig verwendet, um ein Rabatt- oder Zuschlagselement hinzuzufügen, das den Grund für den unterschiedlichen Gesamtbetrag für die ausgewählte Zahlungsmethode angibt, den der Benutzeragent anzeigen kann. Die Eigenschaft nimmt denselben Eingabewert wie die Eigenschaft displayItems des Parameters detailsPromise.

data Optional

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

Zum Beispiel können Sie einen verwenden, um den gesamten Zahlungsbetrag basierend auf der ausgewählten Zahlungsmethode anzupassen ("5% Barzahlungsrabatt!").

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 Versandoption beschreiben, aus der der Benutzer auswählen kann.

total Optional

Ein Objekt mit denselben Eigenschaften wie die Objekte in displayItems, das eine aktualisierte Gesamtsumme für die Zahlung bereitstellt. Stellen Sie sicher, dass dies der Summe aller Elemente in displayItems entspricht. Dies wird nicht automatisch berechnet. Sie müssen diesen Wert selbst aktualisieren, jedes Mal, wenn sich der zu zahlende Gesamtbetrag ändert. Dies gibt Ihnen Flexibilität, wie Sie mit Steuern, Rabatten und anderen Anpassungen des Gesamtpreises umgehen.

Rückgabewert

Ein Promise, das schließlich mit einem PaymentResponse aufgelöst wird. Das Versprechen wird erfüllt, wenn der Benutzer die Zahlungsanforderung akzeptiert (zum Beispiel durch Klicken auf eine „Bezahlen“-Schaltfläche im Zahlungsschirm des Browsers).

Ausnahmen

Ausnahmen werden nicht ausgelöst, sondern zurückgegeben, wenn das Promise abgelehnt wird.

AbortError DOMException

Wird zurückgegeben, wenn der Benutzeragent bereits ein Zahlungsfenster anzeigt. Es kann zu einem Zeitpunkt gemeinsam mit allen von dem Benutzeragent geladenen Dokumenten nur ein Zahlungsfenster sichtbar sein.

Das Versprechen wird auch mit AbortError abgelehnt, wenn der Benutzer die Zahlungsanforderung abbricht.

InvalidStateError DOMException

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

NotSupportedError DOMException

Wird zurückgegeben, wenn der Benutzeragent die in der Konstruktorfunktion von PaymentRequest angegebenen Zahlungsmethoden nicht unterstützt.

SecurityError DOMException

Wird zurückgegeben, wenn der Aufruf von show() nicht als Reaktion auf eine Benutzeraktion, wie z. B. einem click oder keyup-Ereignis, erfolgte. Andere Gründe für das Auslösen eines SecurityError liegen im Ermessen des Benutzeragenten und können Situationen umfassen, wie zu viele show()-Aufrufe in kurzer Zeit oder show()-Aufrufe, während Zahlungsanforderungen durch Kindersicherungen blockiert sind.

Sicherheit

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

Nutzungshinweise

Die gängigsten Muster zur Verwendung von show() beinhalten entweder die async/await-Syntax oder die Verwendung von show().then().catch(), um die Antwort und jede mögliche Ablehnung zu handhaben. Diese sehen folgendermaßen aus:

async/await-Syntax

Das Verwenden von await, um auf das Auflösen eines Versprechens zu warten, ermöglicht das besonders saubere Schreiben von Code zur Zahlungsabwicklung:

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(), ob die Lieferadresse und die Versandoptionen geändert wurden, und liefern als Antwort entweder ein Objekt oder ein Versprechen für eines; dieses Objekt enthält die Felder des PaymentResponse, die geändert wurden oder werden müssen.

Die validateResponse()-Methode unten wird aufgerufen, sobald show() zurückkehrt, um die zurückgegebene response anzusehen und entweder die Zahlung einzureichen 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 prü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() auf der Antwort mit dem String "success" aufgerufen, was anzeigt, dass alles gültig ist und die Zahlung entsprechend abgeschlossen werden kann.

Wenn eines der Felder unzulässige Werte aufweist oder wenn vom vorherigen Code eine Ausnahme ausgelöst wird, wird complete() mit dem String "fail" aufgerufen, der anzeigt, dass der Zahlungsvorgang abgeschlossen und fehlgeschlagen ist.

Statt sofort zu scheitern, könnten Sie sich entscheiden, retry() auf dem Antwortobjekt aufzurufen, um den Benutzeragenten zu bitten, den Zahlungsvorgang erneut zu versuchen; dies sollte normalerweise nur geschehen, nachdem der Benutzer alle erforderlichen Korrekturen an der Bestellung vorgenommen hat.

Den Zahlungsvorgang zu starten ist letztendlich so einfach wie das Aufrufen der Methode processPayment().

then/catch-Syntax

Sie können auch den älteren, versprechensbasierten Ansatz verwenden, um mit Zahlungen zu arbeiten, indem Sie die Funktionen then() und catch() auf das von show() zurückgegebene Versprechen anwenden:

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

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

Sie könnten checkAllValues() sogar als synchrone Funktion haben, obwohl das möglicherweise Leistungsauswirkungen hat, die Sie nicht handhaben möchten:

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

Lesen Sie den Artikel Verwendung von Versprechen, um weitere Informationen zu erhalten, wenn Sie mehr darüber erfahren möchten, wie Sie mit Versprechen arbeiten.

Beispiele

Im folgenden Beispiel wird ein PaymentRequest-Objekt instanziiert, bevor die Methode show() aufgerufen wird. Diese Methode löst den eingebauten Prozess des Benutzeragenten aus, um Zahlungsinformationen vom Benutzer abzurufen. Die Methode show() 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 Zahlungsdaten an den Server zu formatieren und zu senden. Sie sollten die Zahlungsinformationen asynchron an den Server senden, damit der endgültige Aufruf von paymentResponse.complete() den Erfolg oder Misserfolg der Zahlung anzeigen 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 das Zahlungsblatt während seiner Präsentation an den Endnutzer aktualisiert werden kann.

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()