CanMakePaymentEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface CanMakePaymentEvent extends ExtendableEvent

Beschreibung

CanMakePaymentEvent gehört zur Web-Based Payment Handler API. Das Ereignis canmakepayment wird im Service Worker einer registrierten, webbasierten Zahlungs-App ausgelöst, wenn ein Händler eine PaymentRequest anlegt, die eine von der App unterstützte Zahlungsmethode enthält. Das Ergebnis beeinflusst, was der Händler von PaymentRequest.prototype.canMakePayment() zurückbekommt und ob der Browser die App im Zahlungsdialog anbietet.

Die Schnittstelle erbt von ExtendableEvent. Das wichtigste Element ist respondWith(). Die Methode nimmt einen booleschen Wert oder ein Promise entgegen, das zu einem booleschen Wert aufgelöst wird. true heißt: „Diese App kann die Zahlung abwickeln.“ false heißt: „Die App steht gerade nicht zur Verfügung“, etwa weil der Nutzer nicht angemeldet ist oder kein Zahlungsmittel hinterlegt hat.

Frühere Entwürfe der Spezifikation enthielten die Eigenschaften topOrigin, paymentRequestOrigin, methodData und modifiers. Sie wurden aus Datenschutzgründen entfernt, damit eine Zahlungs-App nicht still mitverfolgen kann, auf welchen Seiten ein Nutzer einkauft. Die Entscheidung sollte deshalb nur auf Zuständen innerhalb der App beruhen, zum Beispiel auf dem Anmeldestatus oder gespeicherten Karten.

Das Ereignis wird selten selbst erzeugt. Der Konstruktor new CanMakePaymentEvent(type) ist vor allem für Tests gedacht.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Nur für den Konstruktor: Name des Ereignisses, üblicherweise `"canmakepayment"`.
$eventInitDict	ExtendableEventInit	{}	Nur für den Konstruktor: optionale Initialisierungswerte, die von `ExtendableEvent` geerbt werden, z. B. `bubbles` oder `cancelable`.

Rückgabewert

Typ

CanMakePaymentEvent

Beschreibung

Der Konstruktor liefert eine neue Instanz. respondWith(antwort) selbst gibt undefined zurück. Das Ergebnis wird über das übergebene boolean bzw. Promise<boolean> mitgeteilt.

Beispiele

Einfache Antwort im Service Worker der Zahlungs-App

// sw.js – Service Worker der Zahlungs-App
self.addEventListener('canmakepayment', (event) => {
  // Die App ist immer bereit, Zahlungen anzunehmen
  event.respondWith(true);
});

Asynchrone Prüfung: Ist der Nutzer angemeldet und hat eine Karte hinterlegt?

// sw.js
const hatGespeicherteKarte = async () => {
  const cache = await caches.open('wallet-v1');
  const antwort = await cache.match('/wallet/status.json');
  if (!antwort) return false;
  const { angemeldet, karten } = await antwort.json();
  return angemeldet && karten.length > 0;
};

self.addEventListener('canmakepayment', (event) => {
  // respondWith muss synchron im Handler aufgerufen werden,
  // das Promise darf aber später aufgelöst werden
  event.respondWith(
    hatGespeicherteKarte().catch(() => false)
  );
});

Gegenstück auf der Händlerseite

// shop.js – Seite des Händlers
const methoden = [{ supportedMethods: 'https://bobbucks.example/pay' }];
const details = {
  total: { label: 'Summe', amount: { currency: 'EUR', value: '19.99' } }
};

const pruefen = async () => {
  const request = new PaymentRequest(methoden, details);
  // Das Ergebnis hängt u. a. von respondWith() im Service Worker ab
  const moeglich = await request.canMakePayment();
  console.log('Zahlung möglich:', moeglich);
};

pruefen();

Zahlung möglich: true

Instanziierung für Tests

// Im Service-Worker-Kontext, z. B. für Unit-Tests
const event = new CanMakePaymentEvent('canmakepayment');
console.log(event.type);
console.log(event instanceof ExtendableEvent);

canmakepayment true

// Wichtig · Fallstricke

Kompatibilität: Die Schnittstelle ist experimentell und nur in Chromium-Browsern verfügbar. Firefox und Safari unterstützen die Payment Handler API nicht. Vor der Nutzung sollte man die Unterstützung prüfen, z. B. mit 'CanMakePaymentEvent' in self.
Sie ist nur im Service Worker verfügbar und setzt einen sicheren Kontext (HTTPS) voraus.
respondWith() muss synchron im Event-Handler aufgerufen werden. Nach einem await ist es zu spät, und es wird ein InvalidStateError ausgelöst. Asynchrone Arbeit gehört deshalb in das übergebene Promise.
Wird das Promise abgelehnt oder antwortet der Handler gar nicht, gilt die App als nicht bereit. Mit einem .catch(() => false) ist das Verhalten eindeutig.
Die Antwort sollte schnell kommen. Ein Browser kann eine zu langsame Antwort als false werten.
Das Ereignis wird nur für Apps ausgelöst, die mit registration.paymentManager registriert und über ein Payment-Method-Manifest eingebunden sind. Bei Apps, die erst „just in time“ installiert werden, feuert es nicht. In manchen Browsern feuert es auch im Inkognito-Modus nicht.
Datenschutz: Die früher vorhandenen Eigenschaften topOrigin, paymentRequestOrigin, methodData und modifiers wurden entfernt. Code, der sie noch nutzt, bekommt undefined.

Siehe auch

GamepadEvent AnimationEvent CanvasPattern CommandEvent InterestEvent