Payment Handler API
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.
Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.
Hinweis: Diese Funktion ist in Web Workers verfügbar.
Die Payment Handler API bietet eine standardisierte Funktionalität, mit der Webanwendungen Zahlungen direkt abwickeln können, ohne dass sie zu einer separaten Seite für die Zahlungsabwicklung weitergeleitet werden müssen.
Wenn eine Händler-Website über die Payment Request API eine Zahlung initiiert, kümmert sich die Payment Handler API um das Auffinden geeigneter Zahlungs-Apps. Diese werden dem Benutzer als Auswahl präsentiert. Nachdem der Benutzer eine Auswahl getroffen hat, wird ein Zahlungsfenster geöffnet, in dem er seine Zahlungsdetails eingeben kann, und die Zahlungstransaktion wird mit der Zahlungs-App abgewickelt.
Die Kommunikation mit Zahlungs-Apps (Autorisierung, Übergabe von Zahlungsdaten) erfolgt über Service Worker.
Konzepte und Nutzung
Auf einer Händler-Website wird eine Zahlungsanfrage durch die Erstellung eines neuen PaymentRequest
-Objekts initiiert:
const request = new PaymentRequest(
[
{
supportedMethods: "https://bobbucks.dev/pay",
},
],
{
total: {
label: "total",
amount: { value: "10", currency: "USD" },
},
},
);
Die Eigenschaft supportedMethods
spezifiziert eine URL, die die vom Händler unterstützte Zahlungsmethode darstellt. Wenn Sie mehr als eine Zahlungsmethode verwenden möchten, geben Sie diese in einem Array von Objekten an, wie folgt:
const request = new PaymentRequest(
[
{
supportedMethods: "https://alicebucks.dev/pay",
},
{
supportedMethods: "https://bobbucks.dev/pay",
},
],
{
total: {
label: "total",
amount: { value: "10", currency: "USD" },
},
},
);
Verfügbarmachen von Zahlungs-Apps
In unterstützten Browsern beginnt der Prozess mit dem Anfordern einer Manifestdatei der Zahlungsmethode von jeder URL. Ein Manifest für Zahlungsmethoden wird typischerweise payment-manifest.json
genannt (der genaue Name kann beliebig gewählt werden) und sollte folgendermaßen strukturiert sein:
{
"default_applications": ["https://bobbucks.dev/manifest.json"],
"supported_origins": ["https://alicepay.friendsofalice.example"]
}
Angesichts einer Zahlungsmethodenkennung wie https://bobbucks.dev/pay
, führt der Browser folgende Schritte aus:
- Er beginnt mit dem Laden von
https://bobbucks.dev/pay
und überprüft dessen HTTP-Header.- Wird ein
Link
-Header mitrel="payment-method-manifest"
gefunden, lädt er stattdessen das Manifest der Zahlungsmethode von diesem Ort herunter (siehe Optional, den Browser anderswo das Manifest der Zahlungsmethode finden lassen für Details). - Andernfalls wird der Antwortinhalt von
https://bobbucks.dev/pay
als Manifest der Zahlungsmethode analysiert.
- Wird ein
- Der heruntergeladene Inhalt wird als JSON mit den Mitgliedern
default_applications
undsupported_origins
geparst.
Diese Mitglieder haben folgende Zwecke:
default_applications
gibt dem Browser an, wo die Standard-Zahlungs-App zu finden ist, die die BobBucks-Zahlungsmethode verwenden kann, falls keine installiert ist.supported_origins
gibt dem Browser an, welche anderen Zahlungs-Apps die BobBucks-Zahlung abwickeln dürfen, wenn nötig. Wenn sie bereits auf dem Gerät installiert sind, werden sie dem Benutzer als alternative Zahlungsmöglichkeiten neben der Standardanwendung präsentiert.
Aus dem Manifest der Zahlungsmethode erhält der Browser die URL der Web-App-Manifeste der Standard-Zahlungs-Apps, die beliebig benannt sein können und folgendermaßen aussehen:
{
"name": "Pay with BobBucks",
"short_name": "BobBucks",
"description": "This is an example of the Payment Handler API.",
"icons": [
{
"src": "images/manifest/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "images/manifest/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
],
"serviceworker": {
"src": "service-worker.js",
"scope": "/",
"use_cache": false
},
"start_url": "/",
"display": "standalone",
"theme_color": "#3f51b5",
"background_color": "#3f51b5",
"related_applications": [
{
"platform": "play",
"id": "com.example.android.samplepay",
"min_version": "1",
"fingerprints": [
{
"type": "sha256_cert",
"value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB"
}
]
}
]
}
Wenn die Methode PaymentRequest.show()
von der Händleranwendung als Reaktion auf eine Benutzeraktion aufgerufen wird, verwendet der Browser die Informationen name
und icons
aus jedem Manifest, um dem Benutzer die Zahlungs-Apps in der vom Browser bereitgestellten Payment Request UI zu präsentieren.
- Wenn es mehrere Zahlungs-App-Optionen gibt, wird dem Benutzer eine Liste mit Optionen präsentiert, aus denen er wählen kann. Die Auswahl einer Zahlungs-App startet den Zahlungsprozess, was dazu führt, dass der Browser die Web-App bei Bedarf Just-In-Time (JIT) installiert und den im
serviceworker
-Mitglied spezifizierten Service Worker registriert, damit er die Zahlung abwickeln kann. - Wenn es nur eine Zahlungs-App-Option gibt, wird die Methode
PaymentRequest.show()
den Zahlungsprozess mit dieser Zahlungs-App starten und sie bei Bedarf wie oben beschrieben JIT-installieren. Dies ist eine Optimierung, um dem Benutzer das Präsentieren einer Liste mit nur einer Zahlungs-App-Auswahl zu ersparen.
Hinweis:
Wenn prefer_related_applications
im Zahlungs-App-Manifest auf true
gesetzt ist, wird der Browser die plattformspezifische Zahlungs-App, die in related_applications
spezifiziert ist, starten, um die Zahlung abzuwickeln (sofern verfügbar), anstatt der Web-Zahlungs-App.
Siehe Ein Web-App-Manifest bereitstellen für weitere Details.
Prüfen, ob die Zahlungs-App bereit ist zu zahlen
Die Methode PaymentRequest.canMakePayment()
der Payment Request API gibt true
zurück, wenn eine Zahlungs-App auf dem Gerät des Kunden verfügbar ist, was bedeutet, dass eine Zahlungs-App, die die Zahlungsmethode unterstützt, entdeckt wurde und dass die plattformspezifische Zahlungs-App installiert oder die webbasierte Zahlungs-App bereit zur Registrierung ist.
async function checkCanMakePayment() {
// ...
const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
// Fallback to other means of payment or hide the button.
}
}
Die Payment Handler API fügt einen zusätzlichen Mechanismus hinzu, um die Zahlungsabwicklung vorzubereiten. Das Ereignis canmakepayment
wird im Service Worker einer Zahlungs-App ausgelöst, um zu prüfen, ob es bereit ist, eine Zahlung zu bearbeiten. Insbesondere wird es ausgelöst, wenn die Händler-Website den PaymentRequest()
-Konstruktor aufruft. Der Service Worker kann dann die Methode CanMakePaymentEvent.respondWith()
verwenden, um angemessen zu reagieren:
self.addEventListener("canmakepayment", (e) => {
e.respondWith(
new Promise((resolve, reject) => {
someAppSpecificLogic()
.then((result) => {
resolve(result);
})
.catch((error) => {
reject(error);
});
}),
);
});
Das von respondWith()
zurückgegebene Promise löst sich mit einem Booleschen Wert auf, der signalisiert, ob es bereit ist, eine Zahlungsanfrage zu bearbeiten (true
) oder nicht (false
).
Abwickeln der Zahlung
Nachdem die Methode PaymentRequest.show()
aufgerufen wurde, wird ein paymentrequest
-Ereignis im Service Worker der Zahlungs-App ausgelöst. Dieses Ereignis wird innerhalb des Service Workers der Zahlungs-App überwacht, um die nächste Phase des Zahlungsprozesses zu beginnen.
let payment_request_event;
let resolver;
let client;
// `self` is the global object in service worker
self.addEventListener("paymentrequest", async (e) => {
if (payment_request_event) {
// If there's an ongoing payment transaction, reject it.
resolver.reject();
}
// Preserve the event for future use
payment_request_event = e;
// ...
});
Wenn ein paymentrequest
-Ereignis empfangen wird, kann die Zahlungs-App ein Zahlungsfenster öffnen, indem sie PaymentRequestEvent.openWindow()
aufruft. Das Zahlungsfenster präsentiert den Kunden eine Benutzeroberfläche der Zahlungs-App, in der sie sich authentifizieren, die Versandadresse und Optionen auswählen und die Zahlung autorisieren können.
Nach der Abwicklung der Zahlung wird PaymentRequestEvent.respondWith()
verwendet, um das Zahlungsergebnis an die Händler-Website zurückzugeben.
Siehe Ein Zahlungsanfrageereignis vom Händler empfangen für weitere Details zu dieser Phase.
Verwaltung der Zahlungs-App-Funktionalität
Sobald ein Service Worker für die Zahlungs-App registriert ist, können Sie die Instanz des PaymentManager
des Service Workers (zugänglich über ServiceWorkerRegistration.paymentManager
) verwenden, um verschiedene Aspekte der Funktionalität der Zahlungs-App zu verwalten.
Zum Beispiel:
navigator.serviceWorker.register("serviceworker.js").then((registration) => {
registration.paymentManager.userHint = "Card number should be 16 digits";
registration.paymentManager
.enableDelegations(["shippingAddress", "payerName"])
.then(() => {
// ...
});
// ...
});
PaymentManager.userHint
wird verwendet, um einen Hinweis zusammen mit dem Namen und dem Symbol der Zahlungs-App in der Payment Handler-Benutzeroberfläche anzuzeigen.PaymentManager.enableDelegations()
wird verwendet, um die Verantwortung für das Bereitstellen verschiedener Teile der erforderlichen Zahlungsinformationen an die Zahlungs-App zu delegieren, anstatt sie vom Browser zu sammeln (zum Beispiel über Autofill).
Schnittstellen
CanMakePaymentEvent
-
Das Ereignisobjekt für das
canmakepayment
-Ereignis, das im Service Worker einer Zahlungs-App ausgelöst wird, wenn es erfolgreich registriert wurde, um zu signalisieren, dass es bereit ist, Zahlungen zu bearbeiten. PaymentManager
-
Wird verwendet, um verschiedene Aspekte der Funktionalität einer Zahlungs-App zu verwalten. Zugänglich über die Eigenschaft
ServiceWorkerRegistration.paymentManager
. PaymentRequestEvent
Experimentell-
Das Ereignisobjekt für das
paymentrequest
-Ereignis, das im Service Worker einer Zahlungs-App ausgelöst wird, wenn ein Zahlungsfluss auf der Händler-Website über die MethodePaymentRequest.show()
initiiert wurde.
Erweiterungen zu anderen Schnittstellen
canmakepayment
Ereignis-
Ausgelöst im
ServiceWorkerGlobalScope
einer Zahlungs-App, wenn es erfolgreich registriert wurde, um zu signalisieren, dass es bereit ist, Zahlungen zu bearbeiten. paymentrequest
Ereignis-
Ausgelöst im
ServiceWorkerGlobalScope
einer Zahlungs-App, wenn ein Zahlungsfluss auf der Händler-Website über die MethodePaymentRequest.show()
initiiert wurde. ServiceWorkerRegistration.paymentManager
-
Gibt die Instanz des
PaymentManager
einer Zahlungs-App zurück, die zur Verwaltung verschiedener Zahlungs-App-Funktionalität verwendet wird.
Spezifikationen
Specification |
---|
Payment Handler API # the-paymentrequestevent |
Browser-Kompatibilität
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
PaymentRequestEvent | ||||||||||||
PaymentRequestEvent() constructor | ||||||||||||
changePaymentMethod | ||||||||||||
changeShippingAddress | ||||||||||||
changeShippingOption | ||||||||||||
instrumentKey | ||||||||||||
methodData | ||||||||||||
modifiers | ||||||||||||
openWindow() | ||||||||||||
paymentOptions | ||||||||||||
paymentRequestId | ||||||||||||
paymentRequestOrigin | ||||||||||||
respondWith() | ||||||||||||
shippingOptions | ||||||||||||
topOrigin | ||||||||||||
total |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- No support
- No support
- Experimental. Expect behavior to change in the future.
- Non-standard. Check cross-browser support before using.
- Deprecated. Not for use in new websites.
- See implementation notes.