PaymentRequest: show() Methode

details Optional

Entweder ein Objekt oder ein Promise, das sich zu einem Objekt auflöst. Geben Sie dies an, wenn Ihre Architektur erfordert, dass die Details der Zahlungsanforderung zwischen dem Instanziieren der Zahlungsschnittstelle und dem Beginn der Interaktion des Benutzers damit aktualisiert werden müssen. Das Objekt sollte die aktualisierten Informationen enthalten:

displayItems Optional

Ein Array von Objekten, die jeweils eine Zeilelement für die Zahlungsanforderung beschreiben. Diese repräsentieren die Positionen auf einem Beleg oder einer Rechnung, jeweils mit den folgenden Eigenschaften:

amount

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

currency

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

value

Ein String, der einen gültigen Dezimalwert darstellt, der die Menge der Währung angibt, die den Zahlungsbetrag ausmacht. Dieser String darf nur ein optionales führendes "-" enthalten, um einen negativen Wert anzuzeigen, dann eine oder mehrere Ziffern von 0 bis 9 und einen optionalen Dezimalpunkt (".", unabhängig von der Lokalisierung) gefolgt von mindestens einer weiteren Ziffer. Kein Leerzeichen ist erlaubt.

label

Ein String, der einen menschenlesbaren Namen oder eine Beschreibung des Artikels oder der Dienstleistung angibt, für die berechnet wird. Dies kann dem Benutzer vom Benutzeragenten angezeigt werden, abhängig vom Design der Oberfläche.

pending

Ein Boolean-Wert, der true ist, wenn der angegebene amount noch nicht endgültig festgelegt wurde. Dies kann verwendet werden, um Artikel wie Versand- oder Steuerbeträge anzuzeigen, die von der Auswahl der Versandadresse, Versandoption usw. abhängen. Der Benutzeragent kann diese Informationen anzeigen, ist jedoch nicht verpflichtet, dies zu tun.

error Optional Veraltet Nicht standardisiert

Ein String, der eine Fehlermeldung angibt, die dem Benutzer angezeigt werden soll. Wenn updateWith() aufgerufen wird, verursacht das Hinzufügen von error zu den aktualisierten Daten, dass der Benutzeragent den Text als allgemeine Fehlermeldung anzeigt. Für adressfeldspezifische Fehler verwenden Sie das Feld shippingAddressErrors.

modifiers Optional

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

supportedMethods

Ein String, der den Zahlungsmethoden-Bezeichner repräsentiert. Der Zahlungsmethoden-Bezeichner 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 den gleichen Input wie die total-Eigenschaft des detailsPromise-Parameters.

additionalDisplayItems Optional

Ein Array von Objekten, die zusätzliche Anzeigeelemente bereitstellen, die dem displayItems-Eigentum des detailsPromise-Parameters hinzugefügt werden, wenn diese Zahlungsmethode vom Benutzer ausgewählt wird. Diese Eigenschaft wird häufig verwendet, um einen Rabatt- oder Zuschlagszeilenposten hinzuzufügen, der den Grund für den unterschiedlichen Gesamtbetrag für die ausgewählte Zahlungsmethode angibt, den der Benutzeragent möglicherweise anzeigt. Die Eigenschaft nimmt den gleichen Input wie das displayItems-Eigentum 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önnen Sie einen Modifikator verwenden, um den Gesamtzahlungsbetrag basierend auf der ausgewählten Zahlungsmethode anzupassen ("5% Barzahlungsrabatt!").

shippingAddressErrors Optional Veraltet Nicht standardisiert

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

shippingOptions Optional Veraltet Nicht standardisiert

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

total Optional

Ein Objekt mit den gleichen Eigenschaften wie die Objekte in displayItems, das eine aktualisierte Gesamtsumme für die Zahlung bereitstellt. Stellen Sie sicher, dass dies der Summe aller Artikel in displayItems entspricht. Dies wird nicht automatisch berechnet. Sie müssen diesen Wert selbst aktualisieren, jedes Mal, wenn sich der fällige Gesamtbetrag ändert. Dies ermöglicht Ihnen Flexibilität darin, wie Sie Dinge wie Steuern, Rabatte und andere Anpassungen am Gesamtpreis handhaben.

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

Ausnahmen werden nicht geworfen, sondern zurückgegeben, wenn das Promise abgelehnt wird.

AbortError DOMException

Wird zurückgegeben, wenn der Benutzeragent bereits ein Zahlungsfenster anzeigt. Nur ein Zahlungsfenster darf zu einem Zeitpunkt sichtbar sein über alle vom Benutzeragenten geladenen Dokumente hinweg.

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 Zustand ist interactive, weil sie bereits angezeigt wird).

NotSupportedError DOMException

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

SecurityError DOMException

Wird zurückgegeben, wenn der Aufruf von show() nicht als Reaktion auf eine Benutzeraktion wie ein click oder ein keyup-Ereignis erfolgt. Andere Gründe, warum ein SecurityError ausgelöst werden kann, liegen im Ermessen des Benutzeragenten und können Situationen wie zu viele Aufrufe an show() in kurzer Zeit oder show(), das aufgerufen wird, während Zahlungsanforderungen durch Kinderschutzmaßnahmen blockiert werden, umfassen.

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

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

Die Verwendung von await, um auf die Auflösung eines Versprechens zu warten, ermöglicht es, den Code zur Zahlungsabwicklung besonders sauber 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 prüfen die Methoden checkAddress() und checkShipping(), jeweils die Versandadresse und die Versandoption, und liefern als Antwort entweder ein Objekt oder ein Versprechen, ein solches zurückzugeben; dieses Objekt enthält die Felder in der PaymentResponse, die geändert werden müssen oder wurden.

Die unten stehende Methode validateResponse() wird aufgerufen, sobald show() zurückgegeben wird, um die zurückgegebene response zu überprüfen und entweder die Zahlung abzuschicken 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 sucht eine benutzerdefinierte Funktion namens checkAllValues() jedes Feld in der response durch und stellt sicher, dass sie gültig sind, wobei true zurückgegeben wird, wenn jedes Feld gültig ist, oder false, wenn eines nicht gültig ist. Wenn und nur wenn alle Felder gültig sind, wird die Methode complete() auf der Antwort mit dem String "success" aufgerufen, was angibt, dass alles gültig ist und die Zahlung entsprechend abgeschlossen werden kann.

Wenn irgendwelche Felder unzulässige Werte haben oder wenn der vorherige Code eine Ausnahme auslöst, wird complete() mit dem String "fail" aufgerufen, was bedeutet, dass der Zahlungsvorgang abgeschlossen und fehlgeschlagen ist.

Anstatt sofort zu scheitern, könnten Sie sich entscheiden, retry() auf dem Antwortobjekt aufzurufen, um den Benutzeragenten zu bitten, die Zahlung erneut zu versuchen; dies sollte normalerweise nur gemacht werden, nachdem der Benutzer die benötigten Korrekturen an der Bestellung vorgenommen hat.

Den Zahlungsvorgang zu starten, ist letztlich so einfach wie der 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 auf dem von show() zurückgegebenen Versprechen verwenden:

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 gleichbedeutend mit der 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 checkAllValues() sogar als eine synchrone Funktion haben, obwohl das Leistungsimplikationen haben könnte, mit denen Sie sich nicht auseinandersetzen möchten:

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

Wenn Sie mehr Informationen zu Versprechen benötigen, lesen Sie den Artikel Verwendung von Versprechen.

Im folgenden Beispiel wird ein PaymentRequest-Objekt instanziiert, bevor die show()-Methode aufgerufen wird. Diese Methode löst den eingebauten Prozess des Benutzeragenten aus, um Zahlungsinformationen vom Benutzer abzurufen. Die show()-Methode gibt ein Promise zurück, das sich in ein PaymentResponse-Objekt auflöst, wenn die Benutzerinteraktion abgeschlossen ist. Der Entwickler verwendet dann die Informationen im PaymentResponse-Objekt, um 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 Fehlschlag 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 man das Zahlungsblatt aktualisiert, 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()