Signatur
Beschreibung
PaymentRequest ist der zentrale Einstiegspunkt der Payment Request API. Webseiten und Web-Apps können damit Zahlungen über eine einheitliche, vom Browser bereitgestellte Oberfläche anfordern und müssen dafür kein eigenes Checkout-Formular bauen. Die Seite übergibt dem Konstruktor, welche Zahlungsmethoden sie akzeptiert (etwa Google Pay, Apple Pay oder eine eigene Zahlungs-App-URL) und wie sich der Betrag zusammensetzt. Das Fenster, in dem der Nutzer auswählt und bestätigt, stellt der Browser bzw. die Zahlungs-App.
Der typische Ablauf: Du erzeugst mit new PaymentRequest(methodData, details, options) eine Instanz und prüfst mit canMakePayment(), ob eine passende Zahlungsmethode verfügbar ist. Danach öffnest du mit show() das Bezahlfenster. show() liefert ein Promise auf eine PaymentResponse. Deren Daten schickst du zur Abwicklung an deinen Server und schließt den Vorgang anschließend mit response.complete("success") oder response.complete("fail") ab. Mit abort() brichst du eine laufende Anfrage ab.
Wichtige Mitglieder:
- Methoden:
show(detailsPromise?),canMakePayment(),abort() - Eigenschaften:
idsowie – je nach Browser und nur bei gesetzten Optionen –shippingAddress,shippingOptionundshippingType - Events:
paymentmethodchange; die Eventsshippingaddresschangeundshippingoptionchangesind in vielen Browsern veraltet
Die API setzt einen sicheren Kontext (HTTPS) voraus. show() darf nur als Reaktion auf eine Nutzeraktion aufgerufen werden, etwa in einem Klick-Handler.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $methodData Pflicht | Array<{supportedMethods: string, data?: object}> | Liste der akzeptierten Zahlungsmethoden. supportedMethods ist ein Bezeichner oder eine URL, z. B. "https://google.com/pay" oder "https://apple.com/apple-pay". In data stehen die methodenspezifischen Einstellungen. |
|
| $details Pflicht | PaymentDetailsInit | Angaben zur Transaktion: total ({label, amount: {currency, value}}) ist Pflicht. Optional sind id, displayItems (einzelne Posten), shippingOptions und modifiers (Preisaufschläge oder -nachlässe je Zahlungsmethode). |
|
| $options | PaymentOptions | {} | Legt fest, welche Nutzerdaten abgefragt werden: requestPayerName, requestPayerEmail, requestPayerPhone, requestShipping (alle boolean) und shippingType ("shipping", "delivery" oder "pickup"). Die Unterstützung ist je nach Browser eingeschränkt. |
Rückgabewert
PaymentRequest-Instanz. Das Bezahlfenster erscheint erst, wenn du show() aufrufst.Beispiele
Instanz erzeugen und Verfügbarkeit prüfen
const methods = [{
supportedMethods: 'https://google.com/pay',
data: {
apiVersion: 2,
apiVersionMinor: 0,
allowedPaymentMethods: [{
type: 'CARD',
parameters: { allowedAuthMethods: ['PAN_ONLY'], allowedCardNetworks: ['VISA', 'MASTERCARD'] },
tokenizationSpecification: {
type: 'PAYMENT_GATEWAY',
parameters: { gateway: 'example', gatewayMerchantId: 'demo' }
}
}],
merchantInfo: { merchantName: 'Demo-Shop' }
}
}];
const details = {
total: { label: 'Gesamt', amount: { currency: 'EUR', value: '19.99' } }
};
if ('PaymentRequest' in window) {
const request = new PaymentRequest(methods, details);
const available = await request.canMakePayment();
console.log('Zahlung möglich:', available);
} else {
console.log('Payment Request API nicht unterstützt');
}Kompletter Checkout per Klick mit Einzelposten
const buyButton = document.querySelector('#buy');
buyButton.addEventListener('click', async () => {
const details = {
id: 'order-4711',
displayItems: [
{ label: 'T-Shirt', amount: { currency: 'EUR', value: '15.00' } },
{ label: 'Versand', amount: { currency: 'EUR', value: '4.99' } }
],
total: { label: 'Gesamt', amount: { currency: 'EUR', value: '19.99' } }
};
const request = new PaymentRequest(
[{ supportedMethods: 'https://bobbucks.dev/pay' }],
details,
{ requestPayerEmail: true }
);
try {
const response = await request.show();
// Zahlungsdaten an den Server senden
const res = await fetch('/api/pay', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(response.toJSON())
});
await response.complete(res.ok ? 'success' : 'fail');
console.log(res.ok ? 'Bezahlt!' : 'Zahlung fehlgeschlagen');
} catch (err) {
// AbortError: Nutzer hat abgebrochen
console.log('Abgebrochen:', err.name);
}
});Preis beim Wechsel der Zahlungsmethode anpassen
const request = new PaymentRequest(
[{ supportedMethods: 'https://apple.com/apple-pay', data: { version: 3, merchantIdentifier: 'merchant.example', merchantCapabilities: ['supports3DS'], supportedNetworks: ['visa', 'masterCard'], countryCode: 'DE' } }],
{ total: { label: 'Abo', amount: { currency: 'EUR', value: '9.99' } } }
);
request.addEventListener('paymentmethodchange', (event) => {
console.log('Neue Methode:', event.methodName);
// Aktualisierte Details zurückgeben
event.updateWith({
total: { label: 'Abo (inkl. Gebühr)', amount: { currency: 'EUR', value: '10.49' } }
});
});Anfrage per Timeout abbrechen
const request = new PaymentRequest(
[{ supportedMethods: 'https://bobbucks.dev/pay' }],
{ total: { label: 'Gesamt', amount: { currency: 'EUR', value: '5.00' } } }
);
const timer = setTimeout(() => {
request.abort()
.then(() => console.log('Zahlung nach 60 s abgebrochen'))
.catch((e) => console.warn('Abbruch nicht möglich:', e));
}, 60_000);
document.querySelector('#buy').onclick = async () => {
try {
const response = await request.show();
clearTimeout(timer);
await response.complete('success');
} catch (err) {
console.log(err.name);
}
};