Zahlungsmethode einrichten

Eine Zahlungstransaktion mit Web Payments beginnt mit der Erkennung deiner Zahlungs-App. Hier erfährst du, wie du eine Zahlungsmethode einrichtest und deine Zahlungs-App für Händler und Kunden bereit machst, Zahlungen auszuführen.

Eiji Kitamura

Damit eine Zahlungs-App mit der Payment Request API verwendet werden kann, muss sie mit einer Zahlungsmethoden-ID verknüpft sein. Händler, die eine Zahlungs-App integrieren möchten, verwenden die ID der Zahlungsmethode, um dies dem Browser mitzuteilen. In diesem Artikel wird erläutert, wie die Erkennung von Zahlungs-Apps funktioniert und wie Sie Ihre Zahlungs-App so konfigurieren, dass sie von einem Browser ordnungsgemäß erkannt und aufgerufen wird.

Wenn du mit dem Konzept von Webzahlungen oder der Funktionsweise von Zahlungstransaktionen über Zahlungsanwendungen noch nicht vertraut bist, lies zuerst die folgenden Artikel:

• Unterstützung von Zahlungs-Apps mit Webzahlungen
• Ablauf einer Zahlungstransaktion

Unterstützte Browser

Web Payments besteht aus verschiedenen Technologien. Der Supportstatus hängt vom Browser ab.

	Chromium		Safari		Firefox
	Computer	Android	Computer	Mobilgeräte	Computer/Mobilgeräte
Payment Request API	✔	✔	✔	✔
Payment Handler API	✔	✔
Zahlungs-App für iOS/Android	✔	✔	✔*	✔*

Hinweis : * Safari unterstützt Apple Pay, aber keine Zahlungs-Apps von Drittanbietern.

So erkennt ein Browser eine Zahlungs-App

Jede Zahlungs-App muss Folgendes bieten:

• URL-basierte Kennung für die Zahlungsmethode
• Manifest der Zahlungsmethode (es sei denn, die Zahlungsmethoden-ID wird von einem Dritten bereitgestellt)
• Web-App-Manifest

Der Erkennungsprozess beginnt, wenn ein Händler eine Transaktion initiiert:

1. Der Browser sendet eine Anfrage an die URL der Zahlungsmethode und ruft das Manifest für die Zahlungsmethode ab.
2. Der Browser ermittelt die URL des Web-App-Manifests aus dem Manifest der Zahlungsmethode und ruft das Web-App-Manifest ab.
3. Der Browser bestimmt über das Web-App-Manifest, ob die Zahlungs-App des Betriebssystems oder die webbasierte Zahlungs-App gestartet wird.

In den nächsten Abschnitten wird ausführlich erläutert, wie Sie Ihre eigene Zahlungsmethode einrichten, damit Browser sie erkennen können.

Schritt 1: ID der Zahlungsmethode angeben

Die ID für die Zahlungsmethode ist ein URL-basierter String. Die Google Pay-ID lautet beispielsweise https://google.com/pay. Entwickler von Zahlungs-Apps können eine beliebige URL als Kennung für Zahlungsmethoden auswählen, sofern sie die Kontrolle darüber haben und beliebige Inhalte bereitstellen können. In diesem Artikel verwenden wir https://bobbucks.dev/pay als Zahlungsmethode-ID.

Hinweis : Zahlungs-Apps können auch Zahlungsmethoden von Drittanbietern unterstützen.

So verwenden Händler die Zahlungsmethoden-ID

Ein PaymentRequest-Objekt wird mit einer Liste von Zahlungsmethoden-IDs erstellt, die Zahlungs-Apps identifiziert, die ein Händler akzeptiert. Kennungen für Zahlungsmethoden werden als Wert für das Attribut supportedMethods festgelegt. Beispiel:

[Händler] fordert eine Zahlung an:

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay'
}], {
  total: {
    label: 'total',
    amount: { value: '10', currency: 'USD' }
  }
});

Hinweis : Für eine Zahlungsmethoden-ID in Chrome sind auf derselben Website bis zu dreimal Weiterleitungen zulässig.

Schritt 2: Manifest der Zahlungsmethode bereitstellen

Ein Manifest für Zahlungsmethoden ist eine JSON-Datei, die definiert, welche Zahlungs-App diese Zahlungsmethode verwenden kann.

Manifest der Zahlungsmethode angeben

Wenn ein Händler eine Zahlungstransaktion initiiert, sendet der Browser eine HTTP-GET-Anfrage an die URL der Zahlungsmethoden-ID. Der Server antwortet mit dem Manifest der Zahlungsmethode.

Das Manifest einer Zahlungsmethode hat zwei Felder: default_applications und supported_origins.

Felder des Manifests der Zahlungsmethode

Property-Name	Beschreibung
default_applications (erforderlich)	Ein Array von URLs, die auf Web-App-Manifeste verweisen, in denen die Zahlungs-Apps gehostet werden. (Die URL kann eine relative URL sein.) Dieses Array muss auf das Entwicklungsmanifest, das Produktionsmanifest usw. verweisen.
supported_origins	Ein Array von URLs, die auf Quellen verweisen, auf denen Zahlungs-Apps von Drittanbietern mit derselben Zahlungsmethode gehostet werden können. Eine Zahlungsmethode kann von mehreren Zahlungs-Apps implementiert werden.

Die Manifestdatei einer Zahlungsmethode sollte so aussehen:

[Zahlungs-Handler] /payment-manifest.json:

{
  "default_applications": ["https://bobbucks.dev/manifest.json"],
  "supported_origins": [
    "https://alicepay.friendsofalice.example"
  ]
}

Wenn der Browser das Feld default_applications liest, findet er eine Liste mit Links zu Web-App-Manifesten unterstützter Zahlungs-Apps.

Hinweis : Chrome unterstützt ab Chrome 83 nur noch eine einzige Standard-Zahlungs-App pro Zahlungsmethode.

Optional können Sie den Browser so weiterleiten, dass das Manifest der Zahlungsmethode an einem anderen Ort gefunden wird

Die URL der Zahlungsmethoden-ID kann optional mit einem Link-Header antworten, der auf eine andere URL verweist, unter der der Browser das Manifest der Zahlungsmethode abrufen kann. Das ist nützlich, wenn das Manifest einer Zahlungsmethode auf einem anderen Server gehostet wird oder die Zahlungs-App von einem Dritten bereitgestellt wird.

Konfiguriere den Server für die Zahlungsmethode so, dass er mit einem HTTP-Link-Header mit dem Attribut rel="payment-method-manifest" und der URL des Manifests der Zahlungsmethode antwortet.

Wenn sich das Manifest beispielsweise unter https://bobbucks.dev/payment-manifest.json befindet, enthält der Antwortheader Folgendes:

Link: <https://bobbucks.dev/payment-manifest.json>; rel="payment-method-manifest"

Bei der URL kann es sich um einen voll qualifizierten Domainnamen oder einen relativen Pfad handeln. Prüfen Sie https://bobbucks.dev/pay/ auf Netzwerktraffic, um ein Beispiel zu sehen. Sie können auch den Befehl curl verwenden:

curl --include https://bobbucks.dev/pay

Hinweis : Weitere Informationen zur Vorgehensweise bei Zahlungsmethoden finden Sie in der W3C-Dokumentation.

Schritt 3: Web-App-Manifest bereitstellen

Ein Web-App-Manifest wird verwendet, um eine Web-App, wie der Name schon sagt, zu definieren. Es ist eine häufig verwendete Manifestdatei zur Definition einer progressiven Web-App (PWA).

Ein typisches Web-App-Manifest würde so aussehen:

[Zahlungs-Handler] /manifest.json:

{
  "name": "Pay with Bobpay",
  "short_name": "Bobpay",
  "description": "This is an example of the Payment Handler API.",
  "icons": [
    {
      "src": "images/manifest/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/manifest/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "serviceworker": {
    "src": "service-worker.js",
    "scope": "/",
    "use_cache": false
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.android.samplepay",
      "min_version": "1",
      "fingerprints": [
        {
          "type": "sha256_cert",
          "value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB"
        }
      ]
    }
  ]
}

Die in einem Web-App-Manifest beschriebenen Informationen werden auch verwendet, um festzulegen, wie eine Zahlungs-App in der Benutzeroberfläche für Zahlungsanfragen angezeigt wird.

Wichtige Felder im Manifest für Web-Apps

Property-Name	Beschreibung
name (erforderlich)	Wird als Name der Zahlungs-App verwendet.
icons (erforderlich)	Wird als Symbol der Zahlungs-App verwendet. Diese Symbole werden nur in Chrome verwendet. In anderen Browsern können sie als Fallback-Symbole eingesetzt werden, wenn Sie sie nicht als Teil des Zahlungsmittels angeben.
serviceworker	Wird verwendet, um den Service Worker zu erkennen, der als webbasierte Zahlungsanwendung ausgeführt wird.
serviceworker.src	Die URL, von der das Service Worker-Skript heruntergeladen werden soll.
serviceworker.scope	Ein String, der eine URL darstellt und den Registrierungsbereich eines Service Workers definiert.
serviceworker.use_cache	Die URL, von der das Service Worker-Skript heruntergeladen werden soll.
related_applications	Wird verwendet, um die App zu erkennen, die als vom Betriebssystem bereitgestellte Zahlungs-App fungiert. Weitere Informationen finden Sie im Entwicklerleitfaden für Android-Zahlungs-Apps.
prefer_related_applications	Wird verwendet, um zu bestimmen, welche Zahlungs-App gestartet werden soll, wenn sowohl eine vom Betriebssystem bereitgestellte Zahlungs-App als auch eine webbasierte Zahlungs-App verfügbar sind.

Label und Symbol der Zahlungs-App.

Das Attribut name des Web-App-Manifests wird als Name der Zahlungs-App verwendet, das Attribut icons als Symbol der Zahlungs-App.

So bestimmt Chrome, welche Zahlungs-App gestartet wird

Einführung der plattformspezifischen Zahlungs-App

Damit Sie die plattformspezifische Zahlungs-App starten können, müssen die folgenden Bedingungen erfüllt sein:

• Das Feld related_applications wird im Manifest der Web-App angegeben und gilt für Folgendes:
  • Die Paket-ID und die Signatur der installierten App stimmen überein, während die Mindestversion (min_version) im Manifest der Web-App kleiner oder gleich der Version der installierten App ist.
• Das Feld prefer_related_applications ist true.
• Die plattformspezifische Zahlungs-App ist installiert und hat:
  • Intent-Filter von org.chromium.action.PAY.
  • Eine Kennzeichnung der Zahlungsmethode, die als Wert für das Attribut org.chromium.default_payment_method_name angegeben ist.

Weitere Informationen zur Einrichtung findest du im Entwicklerhandbuch für Android-Zahlungs-Apps.

[Zahlungs-Handler] /manifest.json

"prefer_related_applications": true,
"related_applications": [{
  "platform": "play",
  "id": "xyz.bobpay.app",
  "min_version": "1",
  "fingerprints": [{
    "type": "sha256_cert",
    "value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2:05:0A:1E:57:5F:23:40:E9:E3:87:14:EC:6D:A2:04:21:E0:FD:3B:D1"
  }]
}]

Wenn der Browser festgestellt hat, dass die plattformspezifische Zahlungs-App verfügbar ist, wird der Erkennungsvorgang hier beendet. Andernfalls geht es mit dem nächsten Schritt weiter: dem Starten der webbasierten Zahlungs-App.

Einführung der webbasierten Zahlungs-App

Die webbasierte Zahlungs-App sollte im Feld serviceworker des Manifests der Web-App angegeben werden.

[Zahlungs-Handler] /manifest.json:

"serviceworker": {
  "src": "payment-handler.js"
}

Der Browser startet die webbasierte Zahlungsanwendung durch Senden eines paymentrequest-Ereignisses an den Service Worker. Der Service Worker muss nicht vorab registriert werden. Sie kann genau zum richtigen Zeitpunkt registriert werden.

Informationen zu den speziellen Optimierungen

Wie Browser die Benutzeroberfläche für Zahlungsanforderungen überspringen und eine Zahlungs-App direkt starten können

Wenn in Chrome die Methode show() von PaymentRequest aufgerufen wird, zeigt die Payment Request API eine vom Browser bereitgestellte Benutzeroberfläche namens „Payment Request UI“ an. Über diese Benutzeroberfläche können Nutzer eine Zahlungs-App auswählen. Nach dem Klicken auf die Schaltfläche Weiter in der Benutzeroberfläche für Zahlungsanfragen wird die ausgewählte Zahlungs-App gestartet.

Die Benutzeroberfläche für Zahlungsanfragen wird eingeblendet, bevor die Zahlungs-App gestartet wird.

Wenn vor dem Start einer Zahlungs-App die Benutzeroberfläche für Zahlungsanfragen angezeigt wird, erhöht sich die Anzahl der Schritte, die ein Nutzer zum Ausführen einer Zahlung benötigt. Zur Optimierung des Prozesses kann der Browser die Ausführung dieser Informationen an Zahlungs-Apps delegieren und eine Zahlungs-App direkt starten, ohne beim Aufruf von show() die Benutzeroberfläche für Zahlungsanfragen anzuzeigen.

Überspringen Sie die Benutzeroberfläche für Zahlungsanfragen und starten Sie die Zahlungs-App direkt.

Damit eine Zahlungs-App direkt gestartet werden kann, müssen die folgenden Bedingungen erfüllt sein:

• show() wird durch eine Nutzergeste ausgelöst, z. B. durch einen Mausklick.
• Es gibt nur eine einzige Zahlungs-App, die:
  • Unterstützt die angeforderte Zahlungsart-ID.

Hinweis : Safari unterstützt derzeit nur Apple Pay. Die App wird also immer direkt gestartet, ohne die Benutzeroberfläche für Zahlungsanfragen zu überspringen.

Wann wird eine webbasierte Zahlungs-App Just-in-Time (JIT) registriert?

Webbasierte Zahlungs-Apps können gestartet werden, ohne dass der Nutzer zuvor ausdrücklich die Website der Zahlungs-App besucht und den Service Worker nicht registriert hat. Der Service Worker kann genau zum richtigen Zeitpunkt registriert werden, wenn der Nutzer sich entscheidet, mit der webbasierten Zahlungs-App zu bezahlen. Es gibt zwei Varianten des Registrierungszeitpunkts:

• Wenn dem Nutzer die Benutzeroberfläche für Zahlungsanfragen angezeigt wird, wird die App genau zum richtigen Zeitpunkt registriert und gestartet, wenn der Nutzer auf Weiter klickt.
• Wenn die Benutzeroberfläche für Zahlungsanfragen übersprungen wird, wird die Zahlungsanwendung genau zum richtigen Zeitpunkt registriert und direkt gestartet. Wenn die Benutzeroberfläche für Zahlungsanfragen übersprungen wird, um eine Just-in-time registrierte Anwendung zu starten, ist eine Nutzergeste erforderlich, wodurch eine unerwartete Registrierung von ursprungsübergreifenden Service Workern verhindert wird.

Hinweis : Eine einzelne Zahlungsmethoden-ID kann zwar mehrere Zahlungs-Apps unterstützen, die JIT-Registrierung erfolgt jedoch nur, wenn das Manifest der Zahlungsmethode auf eine einzelne Zahlungs-App verweist.

Nächste Schritte

Nachdem du deine Zahlungs-App nun gefunden hast, kannst du eine plattformspezifische Zahlungs-App und eine webbasierte Zahlungs-App entwickeln.

• Android-Zahlungs-Apps: Entwicklerleitfaden
• Entwicklerleitfaden für webbasierte Zahlungs-Apps