Jak skonfigurować formę płatności

Transakcja płatnicza w ramach płatności internetowych zaczyna się w momencie, gdy wyświetla się Twoja aplikacja płatnicza. Dowiedz się, jak skonfigurować formę płatności i przygotować aplikację płatniczą dla sprzedawców i klientów do dokonywania płatności.

Eiji Kitamura

Aby można było korzystać z interfejsu Payment Request API, aplikacja płatnicza musi być powiązana z identyfikatorem formy płatności. Sprzedawcy, którzy chcą przeprowadzić integrację z aplikacją płatniczą, używają identyfikatora formy płatności, aby wskazać to przeglądarce. Z tego artykułu dowiesz się, jak działa wykrywanie aplikacji do płatności oraz jak skonfigurować aplikację płatniczą, by była odpowiednio wykrywana i wywoływana przez przeglądarkę.

Jeśli nie wiesz, czym są płatności internetowe lub jak działają transakcje w aplikacjach do płatności, przeczytaj najpierw te artykuły:

• Dostęp do aplikacji do płatności dzięki płatnościom internetowym
• Cykl życia transakcji płatności

Obsługiwane przeglądarki

Płatności internetowe składają się z kilku różnych elementów, a stan obsługi może zależeć od przeglądarki.

	Chromium		Safari		Firefox
	Komputer	Android	Komputer	Urządzenia mobilne	Komputer/Urządzenie mobilne
Payment Request API	✔	✔	✔	✔
Interfejs API do obsługi płatności	✔	✔
Aplikacja płatnicza na iOS/Androida	✔	✔	✔*	✔*

Uwaga: *Safari obsługuje Apple Pay, ale nie obsługuje aplikacji płatniczych innych firm.

Jak przeglądarka odkrywa aplikację płatniczą

Każda aplikacja płatnicza musi spełniać te wymagania:

• Identyfikator formy płatności na podstawie adresu URL
• Plik manifestu formy płatności (chyba że identyfikator formy płatności jest podawany przez inną firmę)
• Manifest aplikacji internetowej

Proces wykrywania rozpoczyna się, gdy sprzedawca zainicjuje transakcję:

1. Przeglądarka wysyła żądanie na adres URL z identyfikatorem formy płatności i pobiera plik manifestu formy płatności.
2. Przeglądarka określa adres URL manifestu aplikacji internetowej na podstawie pliku manifestu formy płatności i pobiera plik manifestu aplikacji internetowej.
3. Przeglądarka decyduje, czy uruchomić aplikację płatniczą za system operacyjny, czy internetową aplikację płatniczą, korzystając z pliku manifestu aplikacji internetowej.

W następnych sekcjach wyjaśniamy szczegółowo, jak skonfigurować własną formę płatności, tak aby przeglądarki mogły ją wykryć.

Krok 1. Podaj identyfikator formy płatności

Identyfikator formy płatności to ciąg znaków oparty na adresie URL. Na przykład identyfikator Google Pay to https://google.com/pay. Deweloperzy aplikacji do płatności mogą wybrać dowolny adres URL jako identyfikator formy płatności, o ile mają nad nim kontrolę i mogą wyświetlać dowolne treści. W tym artykule jako identyfikatora formy płatności użyjemy https://bobbucks.dev/pay.

Uwaga: aplikacje do płatności mogą również obsługiwać formy płatności innych firm.

Jak sprzedawcy używają identyfikatora formy płatności

Obiekt PaymentRequest składa się z listy identyfikatorów form płatności identyfikujących aplikacje płatnicze, które sprzedawca akceptuje. Identyfikatory form płatności są ustawione jako wartości właściwości supportedMethods. Na przykład:

[merchant] prosi o płatność:

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

Uwaga: w przypadku identyfikatora formy płatności w Chrome przekierowania w tej samej witrynie są dozwolone maksymalnie 3 razy.

Krok 2. Udostępnij plik manifestu formy płatności

Plik manifestu formy płatności to plik JSON określający, która aplikacja płatnicza może korzystać z danej formy płatności.

Prześlij plik manifestu formy płatności

Gdy sprzedawca inicjuje transakcję płatności, przeglądarka wysyła żądanie HTTP GET na adres URL z identyfikatorem formy płatności. W odpowiedzi serwer przesyła treść manifestu formy płatności.

Plik manifestu formy płatności zawiera 2 pola: default_applications i supported_origins.

Pola pliku manifestu formy płatności

nazwa usługi,	Opis
default_applications (wymagane)	Tablica adresów URL wskazujących pliki manifestu aplikacji internetowych, gdzie są hostowane aplikacje płatnicze. (URL może być względny). Ta tablica powinna odwoływać się do pliku manifestu programowania, pliku manifestu produkcyjnego itp.
supported_origins	Tablica adresów URL wskazujących źródła, które mogą hostować aplikacje płatnicze innych firm z tą samą formą płatności. Pamiętaj, że formę płatności można zaimplementować w wielu aplikacjach płatniczych.

Plik manifestu formy płatności powinien wyglądać tak:

[moduł obsługi płatności] /payment-manifest.json:

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

Gdy przeglądarka odczytuje pole default_applications, znajduje listę linków do plików manifestu aplikacji internetowych obsługiwanych aplikacji do płatności.

Uwaga: od Chrome 83 Chrome obsługuje jedną domyślną aplikację płatniczą na pojedynczą formę płatności.

Opcjonalnie kieruj przeglądarkę, aby znalazła plik manifestu formy płatności w innej lokalizacji

Adres URL identyfikatora formy płatności może opcjonalnie odpowiadać z nagłówkiem Link wskazującym inny adres URL, z którego przeglądarka może pobrać plik manifestu formy płatności. Jest to przydatne, gdy plik manifestu formy płatności jest hostowany na innym serwerze lub gdy aplikacja płatnicza jest udostępniana przez firmę zewnętrzną.

Skonfiguruj serwer form płatności, aby wysyłał w odpowiedzi nagłówek HTTP Link z atrybutem rel="payment-method-manifest" oraz adresem URL pliku manifestu formy płatności.

Jeśli na przykład plik manifestu znajduje się pod adresem https://bobbucks.dev/payment-manifest.json, nagłówek odpowiedzi będzie zawierał te informacje:

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

Adres URL może być pełną i jednoznaczną nazwą domeny lub ścieżką względną. Aby zobaczyć przykład, sprawdź https://bobbucks.dev/pay/ pod kątem ruchu w sieci. Możesz też użyć polecenia curl:

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

Uwaga: więcej informacji o praktykach związanych z formami płatności znajdziesz w dokumentacji W3C.

Krok 3. Udostępnij manifest aplikacji internetowej

Plik manifestu aplikacji internetowej służy do definiowania aplikacji internetowej w sposób sugerujący jej nazwę. Jest to powszechnie używany plik manifestu do definiowania progresywnej aplikacji internetowej (PWA).

Typowy plik manifestu aplikacji internetowej wyglądałby tak:

[moduł obsługi płatności] /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"
        }
      ]
    }
  ]
}

Informacje opisane w pliku manifestu aplikacji internetowej służą też do określania sposobu wyświetlania aplikacji płatniczej w interfejsie Payment Request.

Ważne pola manifestu aplikacji internetowej

nazwa usługi,	Opis
name (wymagane)	Jest używana jako nazwa aplikacji płatniczej.
icons (wymagane)	Używana jako ikona aplikacji płatniczej. Tylko Chrome używa tych ikon. Inne przeglądarki mogą ich używać jako ikon zastępczych, jeśli nie zostaną one określone jako część instrumentu płatniczego.
serviceworker	Służy do wykrywania skryptu service worker, który działa jako internetowa aplikacja płatnicza.
serviceworker.src	Adres URL, z którego można pobrać skrypt skryptu service worker.
serviceworker.scope	Ciąg znaków reprezentujący adres URL, który określa zakres rejestracji skryptu service worker.
serviceworker.use_cache	Adres URL, z którego można pobrać skrypt skryptu service worker.
related_applications	Służy do wykrywania aplikacji, która działa jako aplikacja płatnicza obsługiwana przez system operacyjny. Więcej informacji znajdziesz w przewodniku dla programistów aplikacji do płatności na Androida.
prefer_related_applications	Służy do określania, która aplikacja płatnicza ma zostać uruchomiona, gdy dostępna jest zarówno aplikacja płatnicza obsługiwana przez system operacyjny, jak i internetowa aplikacja płatnicza.

Etykieta i ikona aplikacji do płatności.

Jako nazwę aplikacji płatniczej używana jest właściwość name w pliku manifestu aplikacji internetowej, a jako ikona aplikacji płatniczej używana jest właściwość icons.

Jak Chrome określa, którą aplikację płatniczą uruchomić

uruchomienie aplikacji płatniczej zależnie od platformy,

Aby uruchomić aplikację płatniczą na danej platformie, trzeba spełnić te warunki:

• Pole related_applications jest określone w manifeście aplikacji internetowej oraz:
  • Identyfikator pakietu i podpis aplikacji muszą być takie same, a minimalna wersja (min_version) w pliku manifestu aplikacji internetowej jest równa wersji zainstalowanej aplikacji lub mniejsza.
• Pole prefer_related_applications zawiera wartość true.
• Aplikacja płatnicza przeznaczona na daną platformę jest zainstalowana i ma:
  • Filtr intencji: org.chromium.action.PAY.
  • Identyfikator formy płatności określony jako wartość właściwości org.chromium.default_payment_method_name.

Więcej informacji o ich konfiguracji znajdziesz w przewodniku dla programistów do płatności na Androida.

[moduł obsługi płatności] /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"
  }]
}]

Jeśli przeglądarka stwierdzi, że aplikacja płatnicza na danej platformie jest dostępna, proces wykrywania zostanie zakończony. Jeśli nie, przechodzimy do kolejnego kroku: uruchomieniu internetowej aplikacji płatniczej.

Wprowadzenie internetowej aplikacji do płatności

Internetową aplikację płatniczą należy podać w polu serviceworker w pliku manifestu aplikacji internetowej.

[moduł obsługi płatności] /manifest.json:

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

Przeglądarka uruchamia internetową aplikację płatniczą, wysyłając zdarzenie paymentrequest do skryptu service worker. Skrypt service worker nie musi być wcześniej zarejestrowany. Można ją zarejestrować „just-in-time”.

Informacje o specjalnych optymalizacji

Jak przeglądarki mogą pominąć interfejs Payment Request i bezpośrednio uruchamiać aplikację płatniczą

Po wywołaniu w Chrome metody show() elementu PaymentRequest interfejs PaymentRequest API wyświetla udostępniany przez przeglądarkę interfejs użytkownika o nazwie „Payment Request UI”. Ten interfejs pozwala użytkownikom wybrać aplikację płatniczą. Po naciśnięciu przycisku Kontynuuj w interfejsie żądania płatności zostanie uruchomiona wybrana aplikacja płatnicza.

Interfejs Payment Request interweniuje przed uruchomieniem aplikacji płatniczej.

Wyświetlanie interfejsu żądania płatności przed uruchomieniem aplikacji płatniczej zwiększa liczbę kroków niezbędnych do zrealizowania płatności. Aby zoptymalizować ten proces, przeglądarka może przekazać realizację tych informacji do aplikacji płatniczych i bezpośrednio uruchamiać aplikację płatniczą bez wyświetlania interfejsu prośby o płatności po wywołaniu funkcji show().

Pomiń interfejs żądania płatności i bezpośrednio uruchom aplikację płatniczą.

Aby bezpośrednio uruchomić aplikację płatniczą, trzeba spełnić te warunki:

• Funkcja show() jest wywoływana gestem użytkownika (np. kliknięciem myszą).
• Jest tylko jedna aplikacja płatnicza, która:
  • Obsługuje żądany identyfikator formy płatności.

Uwaga: Safari obecnie obsługuje tylko Apple Pay, więc zawsze uruchamia aplikację bezpośrednio z pominięciem interfejsu Payment Request.

Kiedy internetowa aplikacja do płatności jest rejestrowana „just-in-time” (JIT)?

Internetowe aplikacje płatnicze można uruchamiać bez wyraźnej wcześniejszej wizyty użytkownika na stronie aplikacji płatniczej i zarejestrowania skryptu service worker. Skrypt service worker można zarejestrować właśnie wtedy, gdy użytkownik zdecyduje się zapłacić za pomocą internetowej aplikacji płatniczej. Istnieją 2 warianty czasowe rejestracji:

• Jeśli użytkownik zobaczy interfejs prośby o płatność, aplikacja zostanie zarejestrowana w odpowiednim momencie i uruchomiona, gdy użytkownik kliknie Dalej.
• Jeśli interfejs żądania płatności zostanie pominięty, aplikacja płatnicza zostanie zarejestrowana w sam raz i uruchomiona bezpośrednio. Pominięcie interfejsu Payment Request (żądania płatności) w celu uruchomienia zarejestrowanej aplikacji wymaga gestu użytkownika, który zapobiega nieoczekiwanej rejestracji instancji service worker z innych domen.

Uwaga: 1 identyfikator formy płatności może obsługiwać wiele aplikacji płatniczych, ale rejestracja przy użyciu metody JIT ma miejsce tylko wtedy, gdy plik manifestu formy płatności wskazuje jedną aplikację płatniczą.

Dalsze kroki

Twoja aplikacja płatnicza jest już wykrywalna, więc dowiedz się, jak utworzyć aplikację płatniczą odpowiednią do konkretnej platformy oraz internetową aplikację płatniczą.

• Aplikacje do płatności na Androida: przewodnik dla deweloperów
• Przewodnik dla programistów aplikacji do płatności internetowych