Web-based Payment Handler API

Konzepte und Nutzung

Auf einer Hndler-Website wird eine Zahlungsanfrage durch die Erstellung eines neuen PaymentRequest-Objekts initiiert:

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

Die supportedMethods-Eigenschaft gibt eine URL an, die die vom Hndler untersttzte Zahlungsmethode reprsentiert. Um mehr als eine Zahlungsmethode zu verwenden, wrden Sie sie in einem Array von Objekten angeben, wie folgt:

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

Zahlungsanwendungen verfgbar machen

In untersttzenden Browsern beginnt der Prozess mit der Anforderung einer Zahlungsanwendungsmethodendatei von jeder URL. Ein Zahlungsanwendungsmethodenmanifest wird typischerweise als payment-manifest.json bezeichnet (der genaue Name kann beliebig sein) und sollte wie folgt strukturiert sein:

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

Bei einer Zahlungsanwendungskennung wie https://bobbucks.dev/pay ldt der Browser:

1. Beginnt mit dem Laden von https://bobbucks.dev/pay und prft seine HTTP-Header.
   1. Wenn ein Link-Header mit rel="payment-method-manifest" gefunden wird, ldt er stattdessen das Zahlungsanwendungsmethodenmanifest an diesem Ort herunter (siehe Route den Browser optional, um das Zahlungsanwendungsmethodenmanifest an einem anderen Ort zu finden fr Details).
   2. Andernfalls wird der Antwortinhalt von https://bobbucks.dev/pay als Zahlungsanwendungsmethodenmanifest analysiert.
2. Analysiert den heruntergeladenen Inhalt als JSON mit default_applications und supported_origins-Elementen.

Diese Elemente haben die folgenden Zwecke:

• default_applications teilt dem Browser mit, wo er die Standard-Zahlungsanwendung finden kann, die die BobBucks-Zahlungsmethode verwenden kann, wenn noch keine installiert ist.
• supported_origins teilt dem Browser mit, welche anderen Zahlungsanwendungen berechtigt sind, die BobBucks-Bezahlung bei Bedarf abzuwickeln. Wenn sie bereits auf dem Gert installiert sind, werden sie dem Benutzer als alternative Zahlungsoptionen neben der Standardanwendung prsentiert.

Aus dem Zahlungsanwendungsmethodenmanifest erhlt der Browser die URL der Web-App-Manifestdateien der Standard-Zahlungsanwendungen, die beliebig benannt sein knnen und etwa so aussehen:

{
  "name": "Pay with BobBucks",
  "short_name": "BobBucks",
  "description": "This is an example of the Web-based 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"
        }
      ]
    }
  ]
}

Wenn die PaymentRequest.show()-Methode von der Hndleranwendung als Antwort auf eine Benutzeraktion aufgerufen wird, verwendet der Browser die name- und icons-Informationen, die in jedem Manifest gefunden wurden, um die Zahlungsanwendungen in der browserbasierten Payment Request-Benutzeroberflche dem Benutzer zu prsentieren.

• Wenn es mehrere Zahlungsanwendungsoptionen gibt, wird dem Benutzer eine Liste von Optionen zur Auswahl prsentiert. Die Auswahl einer Zahlungsanwendung startet den Zahlungsablauf, der den Browser bei Bedarf veranlasst, die Web-App "Just-In-Time" (JIT) zu installieren, wobei der im serviceworker-Element angegebene Service Worker registriert wird, damit er die Bezahlung abwickeln kann.
• Wenn es nur eine Zahlungsanwendungsoption gibt, wird die PaymentRequest.show()-Methode den Zahlungsablauf mit dieser Zahlungsanwendung starten, sie bei Bedarf JIT installieren, wie oben beschrieben. Dies ist eine Optimierung, um dem Benutzer keine Liste zu prsentieren, die nur eine Zahlungsanwendungswahl enthlt.

Siehe Dienen eines Web-App-Manifests fr weitere Details.

berprfen, ob die Zahlungsanwendung zahlungsbereit ist

Die PaymentRequest.canMakePayment()-Methode der Payment Request API gibt true zurck, wenn eine Zahlungsanwendung auf dem Gert des Kunden verfgbar ist, d.h. dass eine die Zahlungsmethode untersttzende Zahlungsanwendung entdeckt wurde und die plattformspezifische Zahlungsanwendung installiert ist oder die webbasierte Zahlungsanwendung bereit ist, registriert zu werden.

async function checkCanMakePayment() {
  // 

  const canMakePayment = await request.canMakePayment();
  if (!canMakePayment) {
    // Fallback to other means of payment or hide the button.
  }
}

Die Web-basierte Payment Handler API fgt einen zustzlichen Mechanismus hinzu zur Vorbereitung der Zahlungsabwicklung. Das canmakepayment-Ereignis wird im Service Worker einer Zahlungsanwendung ausgelst, um zu berprfen, ob sie bereit ist, eine Bezahlung zu bearbeiten. Es wird speziell ausgelst, wenn die Hndlerwebsite den PaymentRequest()-Konstruktor aufruft. Der Service Worker kann dann die Methode CanMakePaymentEvent.respondWith() verwenden, um entsprechend zu antworten:

self.addEventListener("canmakepayment", (e) => {
  e.respondWith(
    new Promise((resolve, reject) => {
      someAppSpecificLogic()
        .then((result) => {
          resolve(result);
        })
        .catch((error) => {
          reject(error);
        });
    }),
  );
});

Das von respondWith() zurckgegebene Promise lst sich mit einem booleschen Wert auf, um anzuzeigen, dass es bereit ist, eine Zahlungsanfrage zu bearbeiten (true) oder nicht (false).

Zahlungsabwicklung

Nachdem die PaymentRequest.show()-Methode aufgerufen wurde, wird ein paymentrequest-Ereignis im Service Worker der Zahlungsanwendung ausgelst. Auf dieses Ereignis wird innerhalb des Service Workers der Zahlungsanwendung gehrt, um den nchsten Schritt im Zahlungsprozess zu starten.

let paymentRequestEvent;
let resolver;
let client;

// `self` is the global object in service worker
self.addEventListener("paymentrequest", async (e) => {
  if (paymentRequestEvent) {
    // If there's an ongoing payment transaction, reject it.
    resolver.reject();
  }
  // Preserve the event for future use
  paymentRequestEvent = e;

  // 
});

Wenn ein paymentrequest-Ereignis empfangen wird, kann die Zahlungsanwendung ein Payment-Handler-Fenster ffnen, indem sie PaymentRequestEvent.openWindow() aufruft. Das Payment-Handler-Fenster wird den Kunden eine Schnittstelle der Zahlungsanwendung anbieten, in der sie die Zahlung authentifizieren, eine Versandadresse und Optionen whlen und die Zahlung autorisieren knnen.

Wenn die Zahlung abgewickelt wurde, wird PaymentRequestEvent.respondWith() verwendet, um das Zahlungsergebnis an die Hndlerwebsite zurckzugeben.

Siehe Erhalte ein Zahlungsanfrage-Ereignis vom Hndler fr weitere Details zu diesem Schritt.

Verwaltung der Funktionalitt von Zahlungsanwendungen

Sobald ein Service Worker einer Zahlungsanwendung registriert ist, knnen Sie die PaymentManager-Instanz des Service Workers (zugnglich ber ServiceWorkerRegistration.paymentManager) verwenden, um verschiedene Aspekte der Funktionalitt der Zahlungsanwendung zu verwalten.

Zum Beispiel:

navigator.serviceWorker.register("serviceworker.js").then((registration) => {
  registration.paymentManager.userHint = "Card number should be 16 digits";

  registration.paymentManager
    .enableDelegations(["shippingAddress", "payerName"])
    .then(() => {
      // 
    });

  // 
});

• PaymentManager.userHint wird verwendet, um einen Hinweis fr den Browser bereitzustellen, der zusammen mit dem Namen und Symbol der Zahlungsanwendung in der Web-basierte Payment Handler-Benutzeroberflche angezeigt wird.
• PaymentManager.enableDelegations() wird verwendet, um die Verantwortung fr die Bereitstellung verschiedener Teile der erforderlichen Zahlungsinformationen an die Zahlungsanwendung zu delegieren, anstatt sie ber den Browser zu sammeln (zum Beispiel ber Autofill).

Schnittstellen

CanMakePaymentEvent

Das Ereignisobjekt fr das canmakepayment-Ereignis, das im Service Worker einer Zahlungsanwendung ausgelst wird, wenn sie erfolgreich registriert wurde, um anzuzeigen, dass sie zahlungsbereit ist.

PaymentManager

Wird verwendet, um verschiedene Aspekte der Funktionalitt von Zahlungsanwendungen zu verwalten. Zugriff ber die ServiceWorkerRegistration.paymentManager-Eigenschaft.

PaymentRequestEvent

Das Ereignisobjekt fr das paymentrequest-Ereignis, das im Service Worker einer Zahlungsanwendung ausgelst wird, wenn ein Zahlungsablauf auf der Hndler-Website ber die PaymentRequest.show()-Methode initiiert wurde.

Erweiterungen zu anderen Schnittstellen

canmakepayment Ereignis

Wird im ServiceWorkerGlobalScope einer Zahlungsanwendung ausgelst, wenn sie erfolgreich registriert wurde, um anzuzeigen, dass sie zahlungsbereit ist.

paymentrequest Ereignis

Wird im ServiceWorkerGlobalScope einer Zahlungsanwendung ausgelst, wenn ein Zahlungsablauf auf der Hndler-Website ber die PaymentRequest.show()-Methode initiiert wurde.

ServiceWorkerRegistration.paymentManager

Gibt eine PaymentManager-Instanz einer Zahlungsanwendung zurck, die verwendet wird, um verschiedene Zahlungsanwendungsfunktionen zu verwalten.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• BobBucks Beispiel-Zahlungsanwendung
• bersicht ber webbasierte Zahlungsanwendungen
• Einrichtung einer Zahlungsmethode
• Leben einer Zahlungstransaktion
• Verwendung der Payment Request API
• Konzepte der Zahlungsabwicklung