Jak skonfigurować formę płatności

Transakcja płatnicza z użyciem Web Payments rozpoczyna się od wykrycia Twojej aplikacji płatniczej. Dowiedz się, jak skonfigurować formę płatności i przygotować aplikację płatniczą, aby sprzedawcy i klienci mogli dokonywać płatności.

Eiji Kitamura

Data publikacji: 27 września 2017 r., ostatnia aktualizacja: 1 lipca 2025 r.

Aby można było używać aplikacji do płatności z interfejsem Payment Request API, musi ona być powiązana z identyfikatorem formy płatności. Sprzedawcy, którzy chcą zintegrować się z aplikacją płatniczą, użyją identyfikatora formy płatności, aby poinformować o tym przeglądarkę. Z tego artykułu dowiesz się, jak działa wykrywanie aplikacji do płatności i jak skonfigurować aplikację do płatności, aby była prawidłowo wykrywana i wywoływana przez przeglądarkę.

Jeśli nie znasz koncepcji płatności internetowych ani sposobu działania transakcji płatniczych w aplikacjach płatniczych, najpierw przeczytaj te artykuły:

• Umożliwianie aplikacji płatniczych korzystania z płatności internetowych
• Cykl życia transakcji płatniczej

Obsługa przeglądarek

Web Payments to kilka różnych technologii, a ich obsługa zależy od przeglądarki.

	Chromium		Safari		Firefox
	Komputer	Android	Komputer	Urządzenia mobilne	Komputer/Urządzenie mobilne
Payment Request API	✔	✔	✔	✔
Interfejs Web-based Payment Handler API	✔	✔
Aplikacja płatnicza na iOS lub Androida	✔	✔	✔*	✔*

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

Jak przeglądarka wykrywa aplikację do płatności

Każda aplikacja do płatności musi zawierać te informacje:

• Identyfikator formy płatności oparty na adresie URL
• Plik manifestu formy płatności (z wyjątkiem sytuacji, gdy identyfikator formy płatności jest podawany przez osobę trzecią)
• Manifest aplikacji internetowej

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

1. Przeglądarka wysyła żądanie do adresu URL identyfikatora formy płatności i pobiera plik manifestu formy płatności.
2. Przeglądarka określa adres URL pliku manifestu aplikacji internetowej na podstawie pliku manifestu metody płatności i pobiera plik manifestu aplikacji internetowej.
3. Na podstawie pliku manifestu aplikacji internetowej przeglądarka określa, czy ma uruchomić aplikację do płatności w systemie operacyjnym czy aplikację do płatności w internecie.

W kolejnych sekcjach znajdziesz szczegółowe informacje o tym, jak skonfigurować własną formę płatności, 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ć dowolną treść oraz nagłówki HTTP. W tym artykule jako identyfikatora formy płatności będziemy używać wartości https://bobbucks.dev/pay.

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

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

Obiekt PaymentRequest jest tworzony na podstawie listy identyfikatorów form płatności, które określają aplikacje płatnicze akceptowane przez sprzedawcę. Identyfikatory form płatności są ustawiane jako wartość 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' }
  }
});

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

Manifest formy płatności to plik JSON, który określa, która aplikacja płatnicza może używać tej formy płatności.

Podaj manifest formy płatności

Gdy sprzedawca zainicjuje transakcję płatniczą, przeglądarka wyśle żądanie HTTP HEAD do identyfikatora formy płatności URL. Adres URL identyfikatora formy płatności odpowiada Link nagłówkiem HTTP, który wskazuje adres URL, z którego przeglądarka może pobrać plik manifestu formy płatności.

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

Skonfiguruj serwer formy płatności tak, aby odpowiadał nagłówkiem HTTP Link z atrybutem rel="payment-method-manifest" i adresem URL pliku manifestu formy płatności. Jeśli np. plik manifestu znajduje się pod adresem https://bobbucks.dev/pay/payment-manifest.json, nagłówek odpowiedzi będzie zawierać:

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

Adres URL może być pełną i jednoznaczną nazwą domeny lub ścieżką względną. Przykład znajdziesz w sekcji Inspect https://bobbucks.dev/pay dotyczącej ruchu w sieci. Możesz też użyć polecenia curl:

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

Uwaga: więcej informacji o formach płatności znajdziesz w dokumentacji W3C.

Następnie przeglądarka wysyła żądanie HTTP GET do adresu URL manifestu formy płatności. Serwer odpowiada treścią manifestu formy płatności.

Uwaga: żądanie nie musi być wysyłane do identyfikatora formy płatności w zależności od kombinacji identyfikatora i przeglądarki. Na przykład Chrome nie wysyła żądania dotyczącego https://play.google.com/billing ani – w niektórych przypadkach – https://google.com/pay.

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

Pola manifestu formy płatności

Nazwa usługi	Opis
default_applications (wymagane)	Tablica adresów URL wskazujących pliki manifestu aplikacji internetowych, w których hostowane są aplikacje do płatności. (Adres URL może być względny). Ta tablica powinna odwoływać się do manifestu deweloperskiego, manifestu produkcyjnego itp.
supported_origins	Tablica adresów URL wskazujących źródła, które mogą hostować aplikacje płatnicze innych firm implementujące tę samą formę płatności. Pamiętaj, że formę płatności może obsługiwać kilka aplikacji do płatności.

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

[payment handler] /payment-manifest.json:

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

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

Uwaga: Chrome obsługuje 1 domyślną aplikację do płatności dla każdej formy płatności.

Krok 3. Udostępnij plik manifestu aplikacji internetowej

Plik manifestu aplikacji internetowej służy do definiowania aplikacji internetowej, jak sama nazwa wskazuje. Jest to powszechnie używany plik manifestu, który definiuje progresywną aplikację internetową (PWA).

Typowy manifest aplikacji internetowej wygląda tak:

[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"
        }
      ]
    }
  ]
}

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

Ważne pola manifestu aplikacji internetowej

Nazwa usługi	Opis
name (wymagane)	Używana jako nazwa aplikacji do płatności.
icons (wymagane)	Używana jako ikona aplikacji do płatności. Tych ikon używa tylko Chrome. Inne przeglądarki mogą ich używać jako ikon zastępczych, jeśli nie określisz ich jako części instrumentu płatniczego.
serviceworker	Służy do wykrywania komponentu service worker, który działa jako aplikacja płatnicza online.
serviceworker.src	Adres URL, z którego można pobrać skrypt service worker.
serviceworker.scope	Ciąg znaków reprezentujący adres URL, który określa zakres rejestracji komponentu Service Worker.
serviceworker.use_cache	Adres URL, z którego można pobrać skrypt service worker.
related_applications	Służy do wykrywania aplikacji, która działa jako aplikacja do płatności dostarczana przez system operacyjny. Więcej informacji znajdziesz w przewodniku dla programistów dotyczącym aplikacji do płatności na Androida.
prefer_related_applications	Służy do określania, którą aplikację do płatności uruchomić, gdy dostępne są zarówno aplikacja do płatności dostarczona przez system operacyjny, jak i aplikacja do płatności online.

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

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

Uruchamianie aplikacji płatniczej na konkretnej platformie

Aby uruchomić aplikację do płatności na konkretnej platformie, muszą być spełnione te warunki:

• Pole related_applications jest określone w pliku manifestu aplikacji internetowej i:
  • Identyfikator pakietu i podpis zainstalowanej aplikacji są zgodne, a minimalna wersja (min_version) w manifeście aplikacji internetowej jest mniejsza lub równa wersji zainstalowanej aplikacji.
• Pole prefer_related_applications to true.
• Aplikacja do płatności 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 konfigurowaniu tych ustawień znajdziesz w przewodniku dla deweloperów aplikacji płatniczych na Androida.

[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"
  }]
}]

Jeśli przeglądarka stwierdzi, że aplikacja płatnicza na konkretną platformę jest dostępna, proces wykrywania zostanie zakończony. W przeciwnym razie przechodzi do następnego kroku, czyli uruchomienia aplikacji płatniczej w internecie.

Uruchamianie aplikacji płatniczej w internecie

Aplikacja do płatności w internecie powinna być określona w polu serviceworker w pliku manifestu aplikacji internetowej.

[payment handler] /manifest.json:

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

Przeglądarka uruchamia internetową aplikację płatniczą, wysyłając paymentrequest zdarzenie do procesu roboczego usługi. Skrypt service worker nie musi być zarejestrowany z wyprzedzeniem. Można ją zarejestrować w odpowiednim momencie.

Omówienie specjalnych optymalizacji

Jak przeglądarki mogą pominąć interfejs API Payment Request i bezpośrednio uruchamiać aplikację do płatności

Gdy w Chrome wywoływana jest metoda show() interfejsu PaymentRequest, Payment Request API wyświetla interfejs dostarczony przez przeglądarkę, zwany „interfejsem żądania płatności”. Ten interfejs umożliwia użytkownikom wybór aplikacji do płatności. Po naciśnięciu przycisku Dalej w interfejsie żądania płatności uruchamia się wybrana aplikacja do płatności.

Interfejs żądania płatności pojawia się przed uruchomieniem aplikacji do płatności.

Wyświetlanie interfejsu Payment Request przed uruchomieniem aplikacji płatniczej zwiększa liczbę kroków, które użytkownik musi wykonać, aby zrealizować płatność. Aby zoptymalizować ten proces, przeglądarka może przekazać aplikacjom płatniczym zadanie wypełnienia tych informacji i uruchomić aplikację płatniczą bezpośrednio bez wyświetlania interfejsu Payment Request, gdy wywoływana jest funkcja show().

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

Aby bezpośrednio uruchomić aplikację do płatności, musisz spełnić te warunki:

• show() jest wywoływane przez działanie użytkownika (np. kliknięcie myszą).
• Jest tylko jedna aplikacja do płatności, która:
  • Obsługuje identyfikator żądanej formy płatności.

Uwaga: Safari obsługuje obecnie tylko Apple Pay, więc zawsze uruchamia aplikację bezpośrednio, pomijając interfejs żądania płatności.

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

Aplikacje płatnicze oparte na internecie można uruchamiać bez wyraźnej wcześniejszej wizyty użytkownika w witrynie aplikacji płatniczej i zarejestrowania usługi Service Worker. Service worker może zostać zarejestrowany w odpowiednim momencie, gdy użytkownik zdecyduje się zapłacić za pomocą aplikacji płatniczej opartej na internecie. Istnieją 2 warianty czasu rejestracji:

• Jeśli użytkownikowi wyświetli się interfejs żądania płatności, aplikacja zostanie zarejestrowana w odpowiednim momencie i uruchomiona, gdy użytkownik kliknie Dalej.
• Jeśli interfejs API Payment Request zostanie pominięty, aplikacja do płatności zostanie zarejestrowana w odpowiednim momencie i uruchomiona bezpośrednio. Pomijanie interfejsu Payment Request w celu uruchomienia zarejestrowanej w odpowiednim momencie aplikacji wymaga gestu użytkownika, co zapobiega nieoczekiwanej rejestracji skryptów service worker z innych domen.

Uwaga: jeden identyfikator formy płatności może obsługiwać wiele aplikacji do płatności, ale rejestracja JIT następuje tylko wtedy, gdy plik manifestu formy płatności wskazuje jedną aplikację do płatności.

Następne kroki

Teraz, gdy Twoja aplikacja do płatności jest już widoczna, dowiedz się, jak opracować aplikację do płatności na konkretną platformę i aplikację do płatności w internecie.

• Aplikacje płatnicze na Androida: przewodnik dla programistów
• Przewodnik dla deweloperów po aplikacjach płatniczych opartych na internecie