PaymentResponse.details — Eigenschaft · JavaScript-Referenz

Signatur

PaymentResponse.details

Beschreibung

Die schreibgeschützte Eigenschaft details eines PaymentResponse-Objekts enthält die Antwortdaten der Zahlungsmethode, die der Nutzer im Zahlungsdialog ausgewählt hat. Welche Felder das Objekt hat, hängt vollständig von der Methode ab (siehe PaymentResponse.methodName). Bei Apple Pay steht dort zum Beispiel ein token, bei Google Pay ein paymentMethodData-Objekt samt verschlüsseltem Token, und bei webbasierten Zahlungs-Handlern ist es das Objekt, das der Handler zurückgibt.

Diese Daten bekommt der Händler aus einem einzigen Grund: Er schickt sie an seinen Server oder an seinen Zahlungsdienstleister (PSP), damit dort die Zahlung autorisiert oder belastet wird. Das Objekt ist JSON-serialisierbar. Du kannst es also direkt mit JSON.stringify() in den Body eines fetch()-Aufrufs schreiben. Die Methode PaymentResponse.prototype.toJSON() nimmt details ebenfalls mit auf.

Die Eigenschaft steht bereit, sobald das von PaymentRequest.prototype.show() zurückgegebene Promise erfüllt ist. Wenn der Nutzer seine Angaben über PaymentResponse.prototype.retry() korrigiert, kann sich der Wert danach ändern. Lies details deshalb nach jedem erfolgreichen retry() neu aus.

Rückgabewert

Typ

object

Beschreibung

Ein zahlungsmethodenspezifisches, JSON-serialisierbares Objekt (z. B. Token-Daten von Apple Pay oder Google Pay). Aufbau und Felder legt die jeweilige Zahlungsmethode fest.

Beispiele

Zahlungsdaten nach show() an den Server senden

const methods = [{
  supportedMethods: 'https://google.com/pay',
  data: {
    environment: 'TEST',
    apiVersion: 2,
    apiVersionMinor: 0,
    merchantInfo: { merchantName: 'Beispiel-Shop' },
    allowedPaymentMethods: [{
      type: 'CARD',
      parameters: {
        allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
        allowedCardNetworks: ['VISA', 'MASTERCARD']
      },
      tokenizationSpecification: {
        type: 'PAYMENT_GATEWAY',
        parameters: { gateway: 'example', gatewayMerchantId: 'exampleId' }
      }
    }]
  }
}];

const details = {
  total: { label: 'Summe', amount: { currency: 'EUR', value: '19.99' } }
};

const pay = async () => {
  const request = new PaymentRequest(methods, details);
  const response = await request.show();

  // Methodenspezifische Daten an das eigene Backend übergeben
  const res = await fetch('/api/zahlung', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      methodName: response.methodName,
      details: response.details
    })
  });

  await response.complete(res.ok ? 'success' : 'fail');
};

document.querySelector('#kaufen').addEventListener('click', pay);

Je nach Zahlungsmethode unterschiedlich auswerten

const extractToken = (response) => {
  const { methodName, details } = response;
  switch (methodName) {
    case 'https://apple.com/apple-pay':
      // Apple Pay: details.token.paymentData
      return details.token?.paymentData;
    case 'https://google.com/pay':
      // Google Pay: details.paymentMethodData.tokenizationData.token
      return details.paymentMethodData?.tokenizationData?.token;
    default:
      // Eigener Payment-Handler: kompletten Inhalt weiterreichen
      return details;
  }
};

// Nutzung nach request.show():
// const token = extractToken(response);
// console.log(typeof token);

string

details nach retry() erneut auslesen

const checkout = async (request) => {
  const response = await request.show();
  let ok = await validateOnServer(response.details);

  while (!ok) {
    // Nutzer korrigiert seine Angaben – details kann sich ändern
    await response.retry({ error: 'Zahlung abgelehnt, bitte andere Karte wählen.' });
    ok = await validateOnServer(response.details);
  }
  await response.complete('success');
};

const validateOnServer = async (details) => {
  const res = await fetch('/api/pruefen', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(details)
  });
  return res.ok;
};

// Wichtig · Fallstricke

Sensible Daten: details kann Zahlungstoken oder, bei manchen Handlern, sogar Kartendaten enthalten. Nicht in Logs, localStorage oder an Analyse-Dienste weitergeben. Nur per HTTPS an das eigene Backend oder den PSP übertragen. Wenn Rohdaten von Karten verarbeitet werden, gelten die PCI-DSS-Vorgaben.
Keine feste Struktur: Das Format ist methodenspezifisch. Prüfe immer zuerst methodName und greife nur defensiv auf Felder zu, zum Beispiel mit optionaler Verkettung (?.).
Serverseitig prüfen: Beträge oder Statuswerte aus details nie ungeprüft übernehmen. Die eigentliche Autorisierung muss auf dem Server bzw. beim PSP passieren.
Sicherer Kontext: Die Payment Request API gibt es nur über HTTPS. In iframes funktioniert sie nur mit allow="payment".
Kompatibilität: Unterstützt in Chromium-Browsern und Safari (dort vor allem für Apple Pay). Firefox unterstützt die API standardmäßig nicht. Vorher mit 'PaymentRequest' in window und request.canMakePayment() prüfen.

Siehe auch

PaymentAddress.addressLine PaymentResponse.payerEmail PaymentResponse.methodName PaymentResponse.requestId PaymentResponse.shippingAddress