Zahlungsmethode einrichten

Eine Zahlungstransaktion mit Webzahlungen beginnt mit der Entdeckung Ihrer Zahlungs-App. Hier erfahren Sie, wie Sie eine Zahlungsmethode einrichten und Ihre Zahlungs-App für Händler und Kunden zur Zahlung bereitstellen.

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 einbinden möchten, geben dies dem Browser über die Zahlungsmethoden-ID an. 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, solltest du zuerst die folgenden Artikel lesen:

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

Unterstützte Browser

Web Payments besteht aus mehreren verschiedenen Technologien und der Supportstatus hängt vom Browser ab.

So erkennt ein Browser eine Zahlungs-App

Jede Zahlungs-App muss Folgendes bereitstellen:

• URL-basierte Kennung für die Zahlungsmethode
• Manifest der Zahlungsmethode (außer wenn die Zahlungsmethoden-ID von einem Drittanbieter bereitgestellt wird)
• Manifest der Webanwendung

Der Discovery-Prozess beginnt, wenn ein Händler eine Transaktion initiiert:

1. Der Browser sendet eine Anfrage an die URL der ID der Zahlungsmethode und ruft das Manifest der Zahlungsmethode ab.
2. Der Browser ermittelt die URL des Manifests der Web-App aus dem Manifest der Zahlungsmethode und ruft das Manifest der Web-App ab.
3. Der Browser bestimmt, ob die Zahlungs-App des Betriebssystems oder die webbasierte Zahlungs-App aus dem Manifest der Webanwendung 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: Zahlungsmittel-ID angeben

Ein Zahlungsmethoden-ID ist ein URL-basierter String. Die Kennung für Google Pay 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.

So verwenden Händler die Zahlungsmethoden-ID

Ein PaymentRequest-Objekt enthält eine Liste von Zahlungsmethoden-IDs, die die Zahlungs-Apps angeben, die ein Händler akzeptiert. Zahlungsmethoden-IDs werden als Wert für die Property 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' }
  }
});

Schritt 2: Manifest für Zahlungsmethoden senden

Ein Manifest für Zahlungsmethoden ist eine JSON-Datei, in der festgelegt wird, 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 Zahlungsmethode-ID. Der Server antwortet mit dem Manifest der Zahlungsmethode.

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

Eine Manifestdatei für Zahlungsmethoden sollte so aussehen:

[payment 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.

Optional: Browser anweisen, das Manifest der Zahlungsmethode an einem anderen Ort zu suchen

Die URL der Zahlungsmittel-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 ein Manifest für Zahlungsmethoden auf einem anderen Server gehostet wird oder die Zahlungs-App von einem Drittanbieter 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"

Die URL kann ein voll qualifizierter Domainname oder ein relativer Pfad sein. Sehen Sie sich https://bobbucks.dev/pay/ an, um ein Beispiel für Netzwerkverkehr zu sehen. Sie können auch einen curl-Befehl verwenden:

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

Schritt 3: Web-App-Manifest bereitstellen

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

Ein typisches Manifest für eine Webanwendung sieht so aus:

[payment 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 im Manifest einer Webanwendung beschriebenen Informationen werden auch verwendet, um zu definieren, wie eine Zahlungs-App in der Benutzeroberfläche für Zahlungsanfragen angezeigt wird.

Die Eigenschaft name des Web-App-Manifests wird als Name der Zahlungs-App verwendet, die Eigenschaft icons als Symbol der Zahlungs-App.

So ermittelt Chrome, welche Zahlungs-App gestartet werden soll

Plattformspezifische Zahlungs-App starten

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

• Das Feld related_applications wird im Manifest der Web-App angegeben und:
  • Die Paket-ID und die Signatur der installierten App stimmen überein und die Mindestversion (min_version) im Manifest der Webanwendung ist kleiner oder gleich der Version der installierten Anwendung.
• Das Feld prefer_related_applications ist true.
• Die plattformspezifische Zahlungs-App ist installiert und hat folgende Eigenschaften:
  • Einen Intent-Filter für 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.

[payment 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 wird mit dem nächsten Schritt fortgefahren: 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 Zahlungs-App, indem er ein paymentrequest-Ereignis an den Service Worker sendet. Der Service Worker muss nicht im Voraus registriert werden. Sie kann genau zum richtigen Zeitpunkt registriert werden.

Informationen zu den speziellen Optimierungen

Wie Browser die Benutzeroberfläche für Zahlungsanfragen überspringen und direkt eine Zahlungs-App starten

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

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. Um den Vorgang zu optimieren, kann der Browser die Bereitstellung dieser Informationen an Zahlungs-Apps delegieren und eine Zahlungs-App direkt starten, ohne die Benutzeroberfläche für die Zahlungsanfrage anzuzeigen, wenn show() aufgerufen wird.

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. einen Mausklick).
• Es gibt nur eine Zahlungs-App, die:
  • Unterstützt die angeforderte Zahlungsmethoden-ID.

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

Webbasierte Zahlungs-Apps können gestartet werden, ohne dass der Nutzer zuvor die Website der Zahlungs-App besucht und den Dienst-Worker registriert hat. Der Dienstmitarbeiter kann genau dann registriert werden, wenn der Nutzer mit der webbasierten Zahlungs-App bezahlen möchte. Es gibt zwei Varianten für den Zeitpunkt der Registrierung:

• Wenn dem Nutzer die Zahlungsanfrage-Benutzeroberfläche angezeigt wird, wird die App just-in-time registriert und gestartet, wenn der Nutzer auf Weiter klickt.
• Wenn die Benutzeroberfläche für Zahlungsanfragen übersprungen wird, wird die Zahlungs-App just-in-time registriert und direkt gestartet. Um die Benutzeroberfläche für Zahlungsanfragen zu überspringen und eine Just-in-Time-registrierte App zu starten, ist eine Nutzergeste erforderlich. So wird verhindert, dass Service Worker zwischen verschiedenen Ursprüngen unerwartet registriert werden.

Nächste Schritte

Nachdem Sie dafür gesorgt haben, dass Ihre Zahlungs-App gefunden werden kann, erfahren Sie hier, wie Sie eine plattformspezifische Zahlungs-App und eine webbasierte Zahlungs-App entwickeln.

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