Jak skonfigurować formę płatności

Transakcja płatnicza z użyciem Web Payments zaczyna się od wykrycia Twojej aplikacji płatniczej. Dowiedz się, jak skonfigurować formę płatności i przygotować aplikację płatniczą do dokonywania płatności przez sprzedawców i klientów.

Eiji Kitamura

Data publikacji: 27 września 2017 r., ostatnia aktualizacja: 16 października 2026 r.

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

Jeśli nie masz doświadczenia z płatnościami w internecie, najpierw przeczytaj omówienie płatności w internecie.

Typy aplikacji płatniczych

Forma płatności może być obsługiwana przez aplikację płatniczą na Androida, aplikację płatniczą w przeglądarce lub obie te aplikacje:

• Aplikacja płatnicza na Androida: aplikacja instalowana, którą Chrome uruchamia za pomocą intencji Androida. Chrome weryfikuje nazwę pakietu aplikacji i certyfikat podpisu.
• Aplikacja płatnicza w internecie: skrypt service worker, który Chrome uruchamia w oknie modalnym. Użytkownicy nie muszą niczego instalować.

Aplikacje płatnicze na Androida są dostępne w Chrome na Androidzie i w komponencie WebView. Aplikacje płatnicze działające w przeglądarce są dostępne w Chrome na wszystkich platformach, ale nie w WebView.

Jeśli dla formy płatności dostępne są oba typy aplikacji, a w pliku manifestu aplikacji internetowej ustawiono prefer_related_applications na true, Chrome ukrywa internetową aplikację płatniczą. W przeciwnym razie użytkownicy mogą zobaczyć obie aplikacje w interfejsie żądania zapłaty i wybrać jedną z nich.

Obsługa przeglądarek

Płatności w internecie obejmują kilka różnych technologii, a stan obsługi zależy od przeglądarki.

Jak przeglądarka wykrywa aplikację płatniczą

Każda aplikacja płatnicza musi zawierać te informacje:

• Identyfikator formy płatności oparty na adresie URL
• Plik manifestu formy płatności (chyba że identyfikator formy płatności jest podany przez firmę zewnętrzną)
• Plik manifestu aplikacji internetowej

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

1. Przeglądarka wysyła żądanie do adresu URL identyfikatora formy płatności i pobiera manifest formy płatności.
2. Przeglądarka określa adres URL pliku manifestu aplikacji internetowej na podstawie pliku manifestu formy płatności i pobiera plik manifestu aplikacji internetowej.
3. Przeglądarka określa, czy uruchomić aplikację płatniczą systemu operacyjnego, czy internetową aplikację płatniczą z pliku manifestu aplikacji internetowej.

W kolejnych sekcjach szczegółowo wyjaśniamy, 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 płatniczych mogą wybrać dowolny adres URL jako identyfikator formy płatności, o ile mają nad nim kontrolę i mogą wyświetlać dowolne treści i nagłówki HTTP. W tym artykule jako identyfikatora formy płatności użyjemy https://bobbucks.dev/pay.

Jak sprzedawcy korzystają z identyfikatora formy płatności

Obiekt PaymentRequest jest tworzony z listą identyfikatorów form płatności, które identyfikują 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

Plik manifestu formy płatności to plik JSON, który określa, która aplikacja płatnicza może korzystać z tej formy płatności.

Podaj plik manifestu formy płatności

Gdy sprzedawca inicjuje transakcję płatniczą, przeglądarka wysyła żądanie HTTP HEAD do adresu URL identyfikatora formy płatności. Adres URL identyfikatora formy płatności odpowiada nagłówkiem HTTP Link, który wskazuje adres URL, pod którym przeglądarka może pobrać plik manifestu formy płatności.

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 na przykład 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ą. Aby zobaczyć przykład, sprawdź ruch w sieci na stronie https://bobbucks.dev/pay. Możesz też użyć polecenia curl:

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

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

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

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 manifestów aplikacji internetowych obsługiwanych aplikacji płatniczych.

Krok 3. Udostępnij plik manifestu aplikacji internetowej

Plik manifestu aplikacji internetowej służy do definiowania aplikacji internetowej, jak sugeruje nazwa. 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
  },
  "payment": {
    "supported_delegations": ["shippingAddress", "payerName", "payerEmail", "payerPhone"]
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "prefer_related_applications": true,
  "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"
        }
      ]
    }
  ]
}

Chrome odczytuje różne pola w zależności od typu aplikacji płatniczej. W przypadku aplikacji płatniczej na Androida Chrome odczytuje tylko related_applications. W przypadku internetowej aplikacji płatniczej Chrome odczytuje name, icons, serviceworker, payment i prefer_related_applications.

Właściwość name 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 danej platformie

Aby uruchomić aplikację płatniczą na danej platformie, muszą zostać spełnione te warunki:

• Pole related_applications jest określone w pliku manifestu aplikacji internetowej i:
  • Identyfikator pakietu i podpis aplikacji instalowanej są zgodne, a wersja minimalna (min_version) w pliku manifestu aplikacji internetowej jest mniejsza lub równa wersji zainstalowanej aplikacji.
• Aplikacja płatnicza na daną platformę jest zainstalowana i ma:
  • Filtr intencji org.chromium.intent.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 aplikacji 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 prefer_related_applications to true i dostępna jest aplikacja płatnicza na daną platformę, Chrome ukrywa internetową aplikację płatniczą. W przeciwnym razie Chrome szuka też internetowej aplikacji płatniczej.

Uruchamianie internetowej aplikacji płatniczej

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

[payment handler] /manifest.json:

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

Przeglądarka uruchamia internetową aplikację płatniczą, wysyłając zdarzenie paymentrequest do skryptu service worker. Skryptu service worker nie trzeba rejestrować z wyprzedzeniem. Można je zarejestrować w trybie „just-in-time”.

Omówienie optymalizacji specjalnych

Jak przeglądarki mogą pomijać interfejs żądania płatności i bezpośrednio uruchamiać aplikację płatniczą

W Chrome, gdy wywoływana jest metoda show() interfejsu PaymentRequest, interfejs Payment Request API wyświetla interfejs przeglądarki o nazwie „interfejs Payment Request”. Ten interfejs umożliwia użytkownikom wybór aplikacji płatniczej. Po naciśnięciu przycisku Dalej w interfejsie Payment Request uruchamiana jest wybrana aplikacja płatnicza.

Wyświetlanie interfejsu żądania płatności przed uruchomieniem aplikacji płatniczej zwiększa liczbę kroków, które użytkownik musi wykonać, aby dokonać płatności. Aby zoptymalizować ten proces, przeglądarka może przekazać wypełnianie tych informacji aplikacjom płatniczym i uruchomić aplikację płatniczą bezpośrednio bez wyświetlania interfejsu żądania płatności po wywołaniu show().

Aby uruchomić aplikację płatniczą bezpośrednio, muszą być spełnione te warunki:

• show() jest wywoływany przez gest użytkownika (np. kliknięcie myszą).
• Jest tylko jedna aplikacja płatnicza, która:
  • Obsługuje żądany identyfikator formy płatności.
  • Obsługuje wszystkie informacje o dostawie i dane kontaktowe, o które prosi sprzedawca.

Kiedy internetowa aplikacja płatnicza jest rejestrowana w trybie JIT?

Aplikacje płatnicze działające w przeglądarce można uruchamiać bez konieczności wcześniejszego odwiedzenia przez użytkownika witryny aplikacji płatniczej i zarejestrowania skryptu service worker. Skrypt service worker można zarejestrować w odpowiednim momencie, gdy użytkownik zdecyduje się zapłacić za pomocą internetowej aplikacji płatniczej. Istnieją 2 warianty czasu rejestracji:

• Jeśli użytkownikowi wyświetli się interfejs żądania płatności, aplikacja zostanie zarejestrowana w trybie „just-in-time” i uruchomiona, gdy użytkownik kliknie Dalej.
• Jeśli interfejs Payment Request UI zostanie pominięty, aplikacja płatnicza zostanie zarejestrowana w ostatniej chwili i uruchomiona bezpośrednio. Pominięcie interfejsu Payment Request UI w celu uruchomienia zarejestrowanej aplikacji wymaga gestu użytkownika, co zapobiega nieoczekiwanej rejestracji skryptów service worker ze współdzielonych domen.

Tworzenie internetowej aplikacji płatniczej

Gdy sprzedawca wywołuje show(), Chrome wysyła zdarzenie paymentrequest do skryptu service worker. Wywołaj openWindow() w respondWith(), aby wyświetlić interfejs płatności, a następnie rozwiąż problem, korzystając z odpowiedzi dotyczącej płatności.

Pełny interfejs API znajdziesz w dokumentacji interfejsu Web-Based Payment Handler API na stronie MDN.

Dalsze kroki

• Przewodnik dla programistów aplikacji płatniczych na Androida
• Podawanie informacji o dostawie i danych kontaktowych z aplikacji płatniczej na Androida