Specyfikacja modułu do obsługi płatności w Google Pay

Nazwa modułu obsługi: com.google.pay
Wersja: 2026-01-11

1. Wprowadzenie

Obsługa com.google.pay umożliwia firmom oferowanie Google Pay jako opcji przyspieszonej płatności na platformach zgodnych z UCP. Interfejs Google Pay API umożliwia szybkie płatności, ponieważ daje użytkownikom dostęp do form płatności zapisanych na ich kontach Google.

Ten moduł obsługi umożliwia model integracji bez interfejsu, w którym firmy udostępniają swoją konfigurację Google Pay (np. dozwolone sieci kart i parametry bramy), a platformy obsługują interakcję po stronie klienta z Google Pay API, aby wygenerować bezpieczny token płatności.

1.1 Najważniejsze zalety

Konfiguracja uniwersalna: firmy konfigurują Google Pay tylko raz za pomocą standardowego kodu JSON, co umożliwia każdej autoryzowanej platformie renderowanie interfejsu płatności bez niestandardowego kodu interfejsu.
Oddzielny interfejs: platformy obsługują złożoność integracji interfejsu Google Pay JavaScript API lub pakietu SDK, a firmy korzystają z otrzymanego tokena.
Bezpieczna tokenizacja: wykorzystuje wbudowaną tokenizację Google do przekazywania zaszyfrowanych danych logowania bezpośrednio do dostawcy usług płatniczych firmy.

2. Integracja z firmą

2.1 Wymagania

Przed reklamowaniem Google Pay za pomocą UCP firmy muszą:

Uzyskaj identyfikator sprzedawcy Google Pay: wymagany do przetwarzania w środowisku PRODUCTION (zarejestruj się w Konsoli usług Google Pay i Portfela Google).
Sprawdź, czy dostawca usług płatniczych obsługuje tokenizację: upewnij się, że Twój dostawca usług płatniczych znajduje się na liście obsługiwanych firm i bram obsługujących płatności w przypadku tokenizacji Google Pay.

2.2 Konfiguracja modułu obsługi

Firmy reklamują obsługę Google Pay, umieszczając moduł obsługi w tablicy modułów obsługi płatności. Konfiguracja jest zgodna ze strukturą wymaganą do zainicjowania Google Pay API.

2.2.1 Schemat konfiguracji

Obiekt konfiguracji określa środowisko, tożsamość firmy i dozwolone formy płatności.

Forma płatności w Google Pay

Na podstawie Google Pay PaymentMethod.

Specyfikacja tokenizacji

Na podstawie specyfikacji tokenizacji Google Pay.

2.2.2 Przykładowa deklaracja modułu obsługi

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "01234567890123456789",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": ["PAN_ONLY"],
                "allowed_card_networks": ["VISA", "MASTERCARD"]
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

2.3 Encje

2.3.1 Schemat instrumentu

Instrument Google Pay (card_payment_instrument) rozszerza podstawowy instrument płatniczy. Dziedziczy standardowe pola wyświetlania (np. brand i last_digits), aby zapewnić spójne renderowanie potwierdzenia, a jednocześnie udoskonala pole credential, aby zawierało konkretny ładunek tokenizacji Google Pay.

Działanie platformy: platforma jest odpowiedzialna za mapowanie odpowiedzi Google PayPaymentMethodData na tę strukturę przed wysłaniem jej do firmy.

Nazwa	Typ	Wymagane	Opis
id	ciąg znaków	Tak	Unikalny identyfikator tego instrumentu płatniczego przypisany przez platformę.
handler_id	ciąg znaków	Tak	Identyfikator modułu obsługi Google Pay.
typ	ciąg znaków	Tak	Stała = `card` Wskazuje, że ten instrument zachowuje się jak karta (dziedziczy pola wyświetlania karty).
marka	ciąg znaków	Tak	Sieć kart (np. `visa`, `mastercard`). Odpowiada wartości `info.cardNetwork` w Google Pay.
last_digits	ciąg znaków	Tak	ostatnie 4 cyfry numeru karty; Mapowane z `info.cardDetails` w Google Pay.
rich_text_description	ciąg znaków	Nie	Opcjonalny opis karty w formacie RTF (np. Visa o numerze z końcówką 1234, ważna do 12/2025).
rich_card_art	ciąg znaków (uri)	Nie	Opcjonalny identyfikator URI do obrazu w formacie rich image reprezentującego kartę (np. grafika karty wydawcy).
billing_address	Adres pocztowy	Nie	adres rozliczeniowy powiązany z kartą,
dane logowania	Ładunek danych logowania	Nie	Bezpieczne dane tokenizacji zwrócone przez Google Pay.

Ładunek danych logowania

Ten obiekt służy jako credential instrumentu. Odpowiada bezpośrednio danym tokenizacji Google Pay.

adres pocztowy;

Ten obiekt pełni funkcję pola address. Jest on bezpośrednio powiązany z atrybutem PostalAddress.

3. Integracja platformy

3.1 Wymagania

Zanim platformy zaczną obsługiwać płatności w com.google.pay, muszą:

Musi mieć możliwość wczytywania Google Pay API for Web (lub odpowiednika na Androida).
Podczas renderowania przycisku płatności przestrzegaj wskazówek dotyczących marki Google Pay.

3.2 Protokół płatności

Platformy MUSZĄ postępować zgodnie z tą procedurą, aby przetworzyć moduł obsługi:

Krok 1. Wykrywanie i konfigurowanie

Platforma inicjuje klienta, aby zarządzać cyklem życia interfejsu API.

Odniesienie: PaymentsClient

Krok 2. Sprawdź gotowość do płacenia

Przed wyświetleniem przycisku platforma sprawdza, czy użytkownik może dokonać płatności za pomocą określonych form płatności.

Odniesienie: isReadyToPay

Krok 3. Utwórz żądanie płatności

Platforma tworzy obiekt żądania danych płatności, który zawiera konfigurację sprzedawcy, formy płatności i szczegóły transakcji (cenę i walutę).

Odniesienie: PaymentDataRequest

Krok 4. Wywołaj interakcję użytkownika

Platforma wywołuje wyświetlenie arkusza płatności, gdy użytkownik wejdzie w interakcję z przyciskiem płatności.

Odniesienie: loadPaymentData

Krok 5. Dokończ proces płatności

Po pomyślnej interakcji użytkownika interfejs Google Pay API zwraca obiekt PaymentInstrument pod kluczem payment_data. Platforma mapuje tę odpowiedź na schemat card_payment_instrument i przesyła prośbę o zakończenie płatności.

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "brand": "visa",
    "last_digits": "4242",
    "billing_address": {
      "street_address": "123 Main Street",
      "extended_address": "Suite 400",
      "address_locality": "Charleston",
      "address_region": "SC",
      "postal_code": "29401",
      "address_country": "US",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

4. Przetwarzanie biznesowe

Po otrzymaniu instrumentu płatniczego Google Pay firmy MUSZĄ:

Validate Handler: potwierdź, że handler_id odpowiada modułowi obsługi Google Pay.
Wyodrębnij token: pobierz ciąg tokena z payment_data.credential.token.
Przetwarzanie płatności: przekaż ciąg tokena i szczegóły transakcji do punktu końcowego dostawcy usług płatniczych.
- Uwaga: większość dostawców usług płatniczych ma specjalne pole na „ładunek Google Pay” lub „token sieciowy”.
Odpowiedź zwrotna: odpowiedz z ostatecznym stanem płatności (Sukces/Niepowodzenie).

5. Bezpieczeństwo

5.1 Bezpieczeństwo tokena

PAYMENT_GATEWAY: w przypadku tego typu tokenizacji token jest szyfrowany specjalnie dla podmiotu tokenizującego. Podmiot przekazujący nie może odszyfrować tego tokena i powinien przekazać go do podmiotu tokenizującego w niezmienionej postaci.
BEZPOŚREDNIE: jeśli używasz DIRECT tokenizacji, firma otrzymuje zaszyfrowane dane karty, które musi odszyfrować. Znacznie zwiększa to zakres zgodności ze standardem PCI DSS i nie jest zalecane, chyba że firma jest dostawcą usług zgodnym ze standardem PCI na poziomie 1.

5.2 Izolacja środowiska

Tryb TEST: w środowisku TEST Google Pay zwraca tokeny testowe. Nie można ich obciążyć.
Tryb PRODUKCJA: używane są prawdziwe karty. Firmy muszą zadbać o to, aby dane logowania dostawcy usług płatniczych w config.allowed_payment_methods były zgodne ze środowiskiem.

Specyfikacja modułu do obsługi płatności w Google Pay Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.