Features von übermorgen: die Payment Request API

Inhaltsverzeichnis

Das Implementieren von Bestell- beziehungsweise Bezahlprozessen innerhalb von Webanwendungen kann mitunter recht komplex sein. Die sogenannte Payment Request API, die momentan beim W3C ausgearbeitet wird und vor etwa einem Monat zusammen mit den Payment Method Identifiers als "Candidate Recommendation" veröffentlicht wurde, soll hier Abhilfe schaffen.

Die API sieht vor, den Browser als Vermittler zwischen folgenden bei einem Bestellprozess involvierten Akteuren einzusetzen: dem Zahlungsempfänger (beispielsweise einem Online-Händler), dem Zahlungssender (also dem Käufer) und demjenigen, der die Hilfsmittel für eine Zahlung bereitstellt (Kreditkarte etc.).

Folgende Typen werden durch die API bereitgestellt:

• PaymentRequest: repräsentiert eine Anfrage für einen Bestellprozess.
• PaymentAddress: repräsentiert eine Rechnungsadresse.
• PaymentResponse: repräsentiert die Antwort für einen Bestellprozess.
• PaymentRequestUpdateEvent: Event, das ausgelöst wird, wenn sich die Details einer Bestellanfrage ändern.

Browser-Support

Ob die API vom aktuellen Browser unterstützt wird, lässt sich innerhalb einer Website wie gewohnt über Feature Detection prüfen, beispielsweise durch Überprüfung auf das PaymentRequest-Objekt:

if (window.PaymentRequest) {
  // Payment Request API wird unterstützt
} else {
  // Payment Request API wird nicht unterstützt
}

Momentan unterstützen lediglich Chrome, Opera und Microsoft Edge die API, in Firefox kann die API als experimentelles Feature über das Flag "dom.payments.request.enabled" unter "about:config" aktiviert werden.

Bezahlanfragen formulieren

Um eine Bezahlanfrage zu formulieren, erstellt man eine Instanz von PaymentRequest, wobei dem Konstruktor drei Konfigurationsobjekte als Parameter übergeben werden können:

const methodData = { /* siehe Listings unten */ };
const details = { /* siehe Listings unten */ };
const options = { /* siehe Listings unten */ };
const paymentRequest = new PaymentRequest(
  methodData,
  details,
  options
);

Über methodData lassen sich die zur Verfügung stehenden Bezahlmethoden angeben. Der Eigenschaft supportedMethods kann dabei ein Array von Kennzeichnern für unterstützte Bezahlmethoden hinterlegt werden:

// Konfiguration der Bezahlmethoden
const methodData = [
  {
    supportedMethods: ['basic-card'],
    data: {
      supportedNetworks: ['visa', 'mastercard'],
      supportedTypes: ['debit', 'credit'],
    }
  }
];

Nähere Angaben zu der Bestellung wie etwa Identifikationsnummer einer Bestellung, die zu bestellenden Artikel, Versandkosten etc. lassen sich über das Konfigurationsobjekt details konfigurieren:

// Konfiguration der Bestelldetails
const details = {
  id: 'order-123-12312',
  displayItems: [
    {
      label: 'Summe',
      amount: { currency: 'EUR', value: '25.00' },
    },
    {
      label: 'Mehrwertsteuer',
      amount: { currency: 'EUR', value: '4.75' },
    },
  ],
  shippingOptions: [
    {
      id: 'standard',
      label: 'Standardversand',
      amount: { currency: 'EUR', value: '5.00' },
      selected: true,
    },
    {
      id: 'express',
      label: 'Expressversand',
      amount: { currency: 'EUR', value: '11.00' },
    },
  ],
  total: {
    label: 'Gesamtsumme',
    amount: { currency: 'EUR', value: '34.75' },
  },
};

Über das dritte Konfigurationsobjekt options lässt sich definieren, welche Informationen der Nutzer während des Bestellvorgangs eingeben muss, beispielsweise Name, E-Mail-Adresse oder Telefonnummer:

// Konfiguration der Pflichtangaben
const options = {
  requestPayerEmail: true,
  requestPayerName: true,
  requestPayerPhone: true,
  requestShipping: true,
};

Bezahlanfragen absenden

Um eine Bezahlanfrage zu starten und damit den entsprechenden Dialog zu öffnen, verwendet man die Methode show() am PaymentRequest-Objekt. Zurück gibt die Methode ein Promise-Objekt, das erfüllt wird, wenn der Nutzer den Bezahlprozess über den Dialog abschließt. Innerhalb des darauf folgenden Callbacks lässt sich dann auf die vom Nutzer eingegebenen Daten zugreifen, üblicherweise um sie zur Überprüfung an den Server zu senden (im Folgenden durch den Aufruf von verify() symbolisiert).

// Hier normalerweise Überprüfung durch Server
const verify = (paymentResponse) => Promise.resolve(true);

Der Aufruf der Methode complete() teilt dem Browser anschließend mit, dass der Bezahlprozess abgeschlossen wurde. Als Parameter lassen sich hier die Werte "success" für eine erfolgreiche Bezahlung oder "failure" bei Auftreten eines Fehlers übergeben. Dem Browser steht es laut Spezifikation dann frei, ob er eine entsprechende Meldung anzeigt oder nicht.

paymentRequest.show()
  .then((paymentResponse) => {
      // Zugriff auf die vom Nutzer
      // eingegebenen Daten.
      const {
        requestId,
        methodName,
        details,
        shipping,
        shippingOption,
        payerName,
        payerEmail,
       payerPhone
    } = paymentResponse;
    // verify() als imaginäre Funktion, mit der 
    // die Bezahlanfrage mit der Serverseite überprüft wird
    verify(paymentResponse).then((success) => {
      if (success) {
        console.log('Bezahlung erfolgreich durchgeführt');
        return paymentResponse.complete('success');
      } else {
        console.error('Fehler bei Bezahlung');
        return paymentResponse.complete('failure');
      }
    });
  })
  .catch((error) => {
    console.error('Fehler:', error);
  });

Fazit

Die Payment Request API will Bestell- bzw. Bezahlprozesse innerhalb von Webanwendungen vereinfachen und vereinheitlichen. Wer die API heute schon testen möchte, kann den oben gezeigten Code in einem der zuvor genannten Browser ausführen. Anmerkungen und Verbesserungsvorschläge zur API kann man übrigens über die Issue-Seite des entsprechenden GitHub-Projekts loswerden. ()