new MerchantValidationEvent() — Methode · JavaScript-Referenz

Signatur

new MerchantValidationEvent(type, options)

Beschreibung

Der Konstruktor MerchantValidationEvent() erzeugt ein Ereignisobjekt vom Typ MerchantValidationEvent. Es gehört zur Payment Request API. Der Browser sendet es als merchantvalidation-Ereignis an ein PaymentRequest-Objekt, wenn ein Zahlungsdienstleister (in der Praxis fast ausschließlich Apple Pay) nachweisen will, dass der Händler berechtigt ist, diese Zahlungsmethode zu nutzen.

Im normalen Betrieb erzeugt der Browser das Ereignis selbst. Den Konstruktor ruft man von Hand vor allem in Tests, Mocks und Polyfills auf, zum Beispiel um den Validierungsablauf einer Checkout-Komponente ohne echtes Apple-Pay-Gerät durchzuspielen.

Das erzeugte Objekt stellt die Eigenschaften methodName (Kennung der Zahlungsmethode) und validationURL (URL, von der der Server des Händlers die Händlersitzung abruft) bereit. Dazu kommt die Methode complete(), der man ein Promise mit den Sitzungsdaten übergibt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Laut Spezifikation immer `"merchantvalidation"`.
$options	object	{}	Optionales Wörterbuch. Es erweitert `EventInit`, akzeptiert also auch `bubbles`, `cancelable` und `composed`, und bietet zusätzlich folgende Felder: `methodName` (`string`, Standard `""`): Kennung der Zahlungsmethode (Payment Method Identifier), z. B. `"https://apple.com/apple-pay"`. `validationURL` (`string`, Standard `""`): URL des Validierungsendpunkts des Zahlungsanbieters. Relative Angaben werden gegen die Basis-URL des Dokuments aufgelöst.

Rückgabewert

Typ

MerchantValidationEvent

Beschreibung

Ein neues MerchantValidationEvent-Objekt mit den übergebenen Werten für methodName und validationURL.

Beispiele

Ereignis erzeugen und Eigenschaften auslesen

// Funktionserkennung, da die API fast nur in Safari existiert
if ('MerchantValidationEvent' in window) {
  const event = new MerchantValidationEvent('merchantvalidation', {
    methodName: 'https://apple.com/apple-pay',
    validationURL: 'https://apple-pay-gateway.apple.com/paymentservices/startSession'
  });

  console.log(event.type);
  console.log(event.methodName);
  console.log(event.validationURL);
} else {
  console.log('MerchantValidationEvent wird nicht unterstützt');
}

merchantvalidation https://apple.com/apple-pay https://apple-pay-gateway.apple.com/paymentservices/startSession

Typische Nutzung: Händlervalidierung im Checkout

const methods = [{
  supportedMethods: 'https://apple.com/apple-pay',
  data: {
    version: 3,
    merchantIdentifier: 'merchant.net.programmierung.shop',
    merchantCapabilities: ['supports3DS'],
    supportedNetworks: ['visa', 'masterCard'],
    countryCode: 'DE'
  }
}];
const details = { total: { label: 'Summe', amount: { currency: 'EUR', value: '19.99' } } };

const request = new PaymentRequest(methods, details);

request.addEventListener('merchantvalidation', (event) => {
  // Der eigene Server ruft validationURL mit dem Händlerzertifikat auf
  const session = fetch('/api/apple-pay/session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ validationURL: event.validationURL })
  }).then((res) => res.json());

  // complete() erwartet ein Promise mit der Händlersitzung
  event.complete(session);
});

const response = await request.show();
await response.complete('success');

Validierungs-Handler im Test mit einem selbst erzeugten Ereignis prüfen

// Handler, der getestet werden soll
const handleValidation = (event) => {
  if (event.methodName !== 'https://apple.com/apple-pay') return null;
  return new URL(event.validationURL).hostname;
};

const target = new EventTarget();
let result;
target.addEventListener('merchantvalidation', (e) => { result = handleValidation(e); });

const fakeEvent = new MerchantValidationEvent('merchantvalidation', {
  methodName: 'https://apple.com/apple-pay',
  validationURL: 'https://apple-pay-gateway.apple.com/paymentservices/startSession'
});
target.dispatchEvent(fakeEvent);

console.log(result);

apple-pay-gateway.apple.com

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: MerchantValidationEvent wurde aus der Payment-Request-Spezifikation entfernt. Chrome hat es zeitweise hinter einem Flag angeboten und wieder entfernt, Firefox hat es nie ausgeliefert. Praktisch nutzbar ist es nur in Safari für Apple Pay. Immer mit 'MerchantValidationEvent' in window auf Unterstützung prüfen und als Alternative ApplePaySession mit onvalidatemerchant vorsehen.
Ist validationURL keine gültige URL, wirft der Konstruktor einen TypeError. Ist methodName nicht leer und keine gültige Kennung einer Zahlungsmethode, wird ein RangeError geworfen.
Ein selbst erzeugtes Ereignis hat isTrusted === false. Ein Aufruf von complete() darauf löst beim Browser keine echte Validierung aus. Solche Ereignisse sind nur für Tests und Mocks gedacht.
Sicherheit: Die Anfrage an validationURL muss immer über den eigenen Server laufen, da dafür das private Händlerzertifikat gebraucht wird. Das Zertifikat darf niemals im Client-Code stehen. Prüfe außerdem auf dem Server, dass die URL wirklich zu einer Apple-Domain gehört, sonst droht SSRF (Server-Side Request Forgery).
Die Payment Request API funktioniert nur in sicheren Kontexten (HTTPS).

Siehe auch

new AnimationEvent() new TransitionEvent() new NotificationEvent() new SpeechRecognitionEvent() new CompositionEvent()