PaymentRequest: show() Methode
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.
Die PaymentRequest
-Schnittstelle enthält die
show()
-Methode, die den User-Agent anweist, den Vorgang zu starten, die Benutzeroberfläche für die Zahlungsanforderung dem Benutzer zu zeigen und zu verarbeiten.
Es kann jeweils nur eine Zahlungsanforderung auf einmal, in allen Dokumenten, bearbeitet werden. Sobald die show()
-Methode einer PaymentRequest
-Instanz aufgerufen wird, wird jeder andere Aufruf von show()
mit einem AbortError
abgelehnt, bis das zurückgegebene Versprechen abgeschlossen ist, entweder durch Erfüllung mit einer PaymentResponse
, die die Ergebnisse der Zahlungsanforderung angibt, oder durch Zurückweisung mit einem Fehler.
Hinweis: In der Realität unterstützen einige Browser, einschließlich Firefox, entgegen der Spezifikation, mehrere aktive Zahlungsanforderungen gleichzeitig.
Wenn Ihre Architektur nicht unbedingt alle Daten bereit hat, sie jedoch die Zahlungsoberfläche durch den Aufruf von show()
instanziiert, geben Sie den Parameter detailsPromise
an und übergeben Sie eine Promise
, die erfüllt wird, sobald die Daten bereit sind. Falls vorhanden, lässt show()
nicht zu, dass der Benutzer mit der Zahlungsoberfläche interagiert, bis das Versprechen erfüllt ist, damit Daten vor der Interaktion des Benutzers mit dem Zahlungsprozess aktualisiert werden können.
Die Verarbeitung des Ergebnisses und, falls notwendig, der Aufruf von PaymentResponse.retry()
, um eine fehlgeschlagene Zahlung zu wiederholen, kann entweder asynchron oder synchron erfolgen, je nach Bedarf. Für das beste Benutzererlebnis sind asynchrone Lösungen typischerweise die beste Wahl. Die meisten Beispiele auf MDN und anderswo verwenden async
/await
, um asynchron zu warten, während Ergebnisse validiert werden usw.
Syntax
show()
show(details)
Parameter
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 angegebeneamount
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 underror
in den aktualisierten Daten enthalten ist, zeigt der User-Agent den Text als allgemeine Fehlermeldung an. Für feldspezifische Adressfehler verwenden Sie das FeldshippingAddressErrors
. 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 desdetailsPromise
-Parameters überschreibt, wenn diese Zahlungsmethode vom Benutzer ausgewählt wird. Die Eigenschaft nimmt dieselben Eingaben wie dietotal
-Eigenschaft desdetailsPromise
-Parameters. additionalDisplayItems
Optional-
Ein
Array
von Objekten, die zusätzliche Anzeigeartikel bereitstellen, die derdisplayItems
-Eigenschaft desdetailsPromise
-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 diedisplayItems
-Eigenschaft desdetailsPromise
-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 indisplayItems
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.
Rückgabewert
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
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 einclick
oder einkeyup
-Ereignis. Andere Gründe, warum einSecurityError
ausgelöst werden könnte, liegen im Ermessen des User-Agents und können Situationen wie zu viele Aufrufe vonshow()
in kurzer Zeit odershow()
-Aufrufe umfassen, wenn Zahlungsanforderungen durch Kindersicherungen blockiert werden.
Sicherheit
Transiente Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.
Verwendungsnotizen
async/await-Syntax
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.
then/catch-Syntax
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.
Beispiele
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;
Spezifikationen
Specification |
---|
Payment Request API # dom-paymentrequest-show |
Browser-Kompatibilität
BCD tables only load in the browser