Interfejs Google Pay API for Web – podstawy

1. Wprowadzenie

Co utworzysz

Po ukończeniu tego ćwiczenia będziesz mieć działającą witrynę z minimalną funkcjonalnością i zintegrowaną usługą Google Pay. Ten projekt pobiera token płatności, który może zostać wysłany do dostawcy usług płatniczych w celu przetworzenia.

Czego się nauczysz

Jak wczytać i skonfigurować Google Pay API
Wyświetlanie przycisku Google Pay i obsługa kliknięć
Jak poprosić o token płatności w Google Pay

Czego potrzebujesz

edytor tekstu do edytowania plików HTML i JavaScript;
Przeglądarka Google Chrome lub inny sposób na przetestowanie lokalnej witryny.
W przypadku środowiska produkcyjnego potrzebujesz merchantId Google Pay. Rejestracja w Konsoli usług Google Pay i Portfela Google zajmuje tylko minutę, więc warto to zrobić od razu.

Korzystanie z Firebase Studio

2. Tworzenie strony HTML

Tworzenie plików projektu

Utwórz na komputerze folder o nazwie gpay-web-101, a w nim 2 puste pliki tekstowe o nazwach index.html i main.js.Struktura katalogu powinna wyglądać tak:
```
gpay-web-101/
  index.html
  main.js
```

Otwórz plik index.html w wybranym IDE i dodaj ten kod:

<!doctype html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Google Pay API for Web 101</title>
</head>

<body>
  <div id="gpay-container"></div>
  <p>Transaction info and errors will be logged to the console.</p>
  <script type="text/javascript" src="main.js"></script>
  <script
    async src="https://pay.google.com/gp/p/js/pay.js"
    onload="onGooglePayLoaded()">
  </script>
</body>

</html>

Wyjaśnienie kodu

Do strony zostanie dodany pusty element DIV z identyfikatorem gpay-container. Ten element DOM będzie elementem nadrzędnym, do którego zostanie dodany przycisk Google Pay. Możesz umieścić ten element w odpowiednim miejscu w układzie witryny.
Tag skryptu main.js jest umieszczany w DOM po elemencie gpay-container. Jest to konieczne, aby mieć pewność, że element DIV kontenera jest obecny w DOM przed wysłaniem do niego zapytań przez main.js. Dodatkowo skrypt jest synchroniczny, aby mieć pewność, że zostanie załadowany przed pay.js, ponieważ metoda onGooglePayLoaded() musi istnieć przed zakończeniem ładowania. Istnieją inne sposoby osiągnięcia tego samego efektu, ale nie będziemy ich tu omawiać.
Na koniec pay.js jest wczytywany asynchronicznie i konfiguruje onGooglePayLoaded() jako jego moduł obsługi onload. Ta metoda zostanie zdefiniowana w main.js.

3. Konfigurowanie Google Pay

Żądanie płatności Google Pay wymaga obiektu żądania. Obiekt zdefiniowany tutaj jako baseGooglePayRequest zawiera minimalne wspólne ustawienia wszystkich żądań. W zależności od zgłoszonego żądania zostaną dodane dodatkowe ustawienia, które omówimy w tym laboratorium.

Dodaj do pustego pliku main.js stałe konfiguracji Google Pay:

//=============================================================================
// Configuration
//=============================================================================

// The DOM element that the Google Pay button will be rendered into
const GPAY_BUTTON_CONTAINER_ID = 'gpay-container';

// Update the `merchantId` and `merchantName` properties with your own values.
// Your real info is required when the environment is `PRODUCTION`.
const merchantInfo = {
  merchantId: '12345678901234567890',
  merchantName: 'Example Merchant'
};

// This is the base configuration for all Google Pay payment data requests.
const baseGooglePayRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [
    {
      type: 'CARD',
      parameters: {
        allowedAuthMethods: [
          "PAN_ONLY", "CRYPTOGRAM_3DS"
        ],
        allowedCardNetworks: [
          "AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"
        ]
      },
      tokenizationSpecification: {
        type: 'PAYMENT_GATEWAY',
        parameters: {
          gateway: 'example',
          gatewayMerchantId: 'exampleGatewayMerchantId'
        }
      }
    }
  ],
  merchantInfo
};

// Prevent accidental edits to the base configuration. Mutations will be
// handled by cloning the config using deepCopy() and modifying the copy.
Object.freeze(baseGooglePayRequest);

Wyjaśnienie kodu

Ustaw zmienną stałą GPAY_BUTTON_CONTAINER_ID na identyfikator elementu DOM używanego na stronie HTML jako kontenera nadrzędnego przycisku Google Pay.
Utwórz obiekt konfiguracji baseGooglePayRequest z odpowiednimi ustawieniami aplikacji. Każda z właściwości i wartości jest opisana w dokumentacji referencyjnej. Wartości podane w tym przykładzie mogą nie w pełni odpowiadać Twoim potrzebom, więc dokładnie je sprawdź.
Zaktualizuj właściwości merchantId i merchantName, podając własne wartości. Te pola są opcjonalne, gdy środowisko to TEST.

Zasoby

Post na blogu: Chcesz płacić szybciej dzięki Google Pay? Skonfiguruj opcje płatności!
Dokumentacja API: dokumentacja obiektów żądań interfejsu Google Pay API
Dokumentacja interfejsu API: więcej informacji o dozwolonych metodach autoryzacji, dozwolonych sieciach kart i specyfikacjach tokenizacji, w tym o prawidłowej wartości bramy, znajdziesz w PaymentMethod.

4. Dodawanie klienta płatności

Klient płatności służy do wysyłania żądań płatności i rejestrowania wywołań zwrotnych. W tym ćwiczeniu będziemy wysyłać tylko prośby o płatność. Możesz też skonfigurować PaymentDataCallbacks tak, aby obsługiwał sytuacje, w których zmieniły się dane płatności lub autoryzacja. Te zaawansowane tematy nie są jednak omawiane w tym laboratorium.

Dodaj ten kod klienta na końcu pliku main.js:

//=============================================================================
// Google Payments client singleton
//=============================================================================

let paymentsClient = null;

function getGooglePaymentsClient() {
  if (paymentsClient === null) {
    paymentsClient = new google.payments.api.PaymentsClient({
      environment: 'TEST',
      merchantInfo,
      // todo: paymentDataCallbacks (codelab pay-web-201)
    });
  }

  return paymentsClient;
}

Wyjaśnienie kodu

Zmienna paymentsClient będzie przechowywać instancję klienta po jej utworzeniu. Do zmiennej nie uzyskuje się dostępu bezpośrednio za pomocą naszego kodu, ale zawsze za pomocą metody getGooglePaymentsClient().
Metoda getGooglePaymentsClient() sprawdza, czy klient został już utworzony, i zwraca tę instancję. Jeśli wcześniej nie został utworzony, zostanie utworzony, zapisany i zwrócony. Ta metoda zapewnia, że w całym okresie działania skryptu zostanie utworzona i użyta tylko jedna instancja.
Aby utworzyć instancję klienta, wywołaj metodę PaymentsClient(). W tym przykładzie informujemy klienta, że jesteśmy w środowisku TEST. Alternatywą jest PRODUCTION. Wartość TEST jest jednak domyślna i można ją pominąć.

5. Dodawanie pomocników

Poniższe funkcje pomocnicze są używane w dalszej części skryptu i zostały dodane wyłącznie w celu zwiększenia czytelności i łatwości konserwacji kodu.

Dołącz funkcje pomocnicze na końcu pliku main.js:

//=============================================================================
// Helpers
//=============================================================================

const deepCopy = (obj) => JSON.parse(JSON.stringify(obj));

function renderGooglePayButton() {
  const button = getGooglePaymentsClient().createButton({
    onClick: onGooglePaymentButtonClicked
  });

  document.getElementById(GPAY_BUTTON_CONTAINER_ID).appendChild(button);
}

Wyjaśnienie kodu

deepCopy() to narzędzie, które używa serializacji i deserializacji JSON do utworzenia głębokiej kopii podanego obiektu. To wygodny sposób na klonowanie obiektów bez obaw o wspólne odwołania.
renderGooglePayButton() to narzędzie, które wywołuje metodę biblioteki createButton(), aby wyświetlić przycisk Google Pay. Przekazywany argument to zestaw opcji, które określają sposób działania przycisku, np. rejestrowanie funkcji onGooglePaymentButtonClicked() do obsługi kliknięć przycisku.

6. Dodawanie modułów obsługi zdarzeń

W tym skrypcie konfigurujemy 2 moduły obsługi zdarzeń. Pierwsza jest wywoływana, gdy biblioteka pay.js zakończy wczytywanie, a druga – gdy klikniesz przycisk Google Pay.

Dołącz moduły obsługi zdarzeń na końcu pliku main.js:

//=============================================================================
// Event Handlers
//=============================================================================

function onGooglePayLoaded() {
  const req = deepCopy(baseGooglePayRequest);

  getGooglePaymentsClient()
    .isReadyToPay(req)
    .then(function(res) {
      if (res.result) {
        renderGooglePayButton();
      } else {
        console.log("Google Pay is not ready for this user.");
      }
    })
    .catch(console.error);
}

function onGooglePaymentButtonClicked() {
  // Create a new request data object for this request
  const req = {
    ...deepCopy(baseGooglePayRequest),
    transactionInfo: {
      countryCode: 'US',
      currencyCode: 'USD',
      totalPriceStatus: 'FINAL',
      totalPrice: (Math.random() * 999 + 1).toFixed(2),
    },
    // todo: callbackIntents (codelab gpay-web-201)
  };

  // Write request object to console for debugging
  console.log(req);

  getGooglePaymentsClient()
    .loadPaymentData(req)
    .then(function (res) {
      // Write response object to console for debugging
      console.log(res);
      // @todo pass payment token to your gateway to process payment
      // @note DO NOT save the payment credentials for future transactions
      paymentToken = res.paymentMethodData.tokenizationData.token;
    })
    .catch(console.error);
}

Wyjaśnienie kodu

Funkcja onGooglePayLoaded() jest wywoływana po zakończeniu wczytywania skryptu pay.js zgodnie z definicją w pliku HTML. Wywoływana jest metoda isReadyToPay(), aby określić, czy wyświetlić przycisk Google Pay. Jeśli klient jest gotowy do zapłaty (czyli dodał formę płatności do Portfela Google), przycisk Google Pay zostanie wyświetlony.
onGooglePaymentButtonClicked() jest wywoływana po kliknięciu przycisku Google Pay. Ta metoda wywołuje metodę biblioteki loadPaymentData(), która służy do pobierania tokena płatności. Po uzyskaniu tokena płatności należy przesłać go do bramy płatności w celu przetworzenia transakcji. transactionInfo opisuje transakcję, która powinna zostać przetworzona po kliknięciu tego przycisku.

7. Podsumowanie

Gratulujemy ukończenia tego ćwiczenia! Wiesz już, jak zintegrować interfejs Google Pay API z witryną.

Uruchamianie projektu

Testowanie w Google Chrome

W przeglądarce Google Chrome otwórz plik index.html, klikając Plik > Otwórz plik... w menu głównym Chrome. Chrome wykona main.js, gdy projekt zostanie otwarty w ten sposób. Inne przeglądarki mogą nie zezwalać na wykonywanie kodu JavaScript.

– lub –

Testowanie za pomocą lokalnego serwera WWW

Jeśli masz zainstalowany język Python, uruchom polecenie python3 -m http.server w wierszu poleceń terminala w folderze głównym pay-web-101.

$ cd /your/path/to/pay-web-101
$ python3 -m http.server
Serving HTTP on :: port 8000 (http://[::]:8000/) ...

Następnie otwórz witrynę pod adresem http://localhost:8000.

Co dalej

Dodatkowe materiały

Dołącz do rozmowy na kanale#payments w Discordzie
Obserwuj @GooglePayDevs na X
Oglądaj filmy związane z Google Pay w YouTube