Obsługa opcjonalnych danych karty za pomocą skryptu service worker

Jak dostosować internetową aplikację do płatności do płatności internetowych i zapewnić klientom lepsze wrażenia.

Eiji Kitamura

Gdy aplikacja do płatności internetowej otrzyma żądanie płatności i rozpocznie transakcję płatności, usługa robocza będzie pełnić funkcję centrum komunikacji między sprzedawcą a aplikacją do płatności. W tym poście wyjaśniamy, jak aplikacja do płatności może przekazywać informacje o formie płatności, adresie dostawy lub danych kontaktowych sprzedawcy za pomocą usługi roboczej.

Poinformuj sprzedawcę o zmianie formy płatności

Aplikacje do płatności mogą obsługiwać wiele instrumentów płatniczych z różnymi formami płatności.

Na przykład w tabeli powyżej portfel internetowy klienta A ma 2 karty kredytowe i 1 konto bankowe. W tym przypadku aplikacja obsługuje 3 instrumenty płatności (****1234, ****4242, ******123) i 2 metody płatności (wydawca karty kredytowej 1 i bank X). Podczas transakcji płatniczej aplikacja płatnicza może pozwolić klientowi wybrać jeden z instrumentów płatniczych i użyć go do zapłaty za towar sprzedawcy.

Aplikacja do płatności może poinformować sprzedawcę, którą formę płatności wybrał klient, zanim wyśle pełną odpowiedź na płatność. Jest to przydatne, gdy sprzedawca chce na przykład uruchomić kampanię rabatową dla konkretnej marki formy płatności.

Dzięki interfejsowi Payment Handler API aplikacja płatnicza może wysłać zdarzenie „zmianę formy płatności” do sprzedawcy za pomocą workera usługowego, aby powiadomić o nowym identyfikatorze formy płatności. Pracownik usługi powinien wywołać PaymentRequestEvent.changePaymentMethod() z informacjami o nowej formie płatności.

Aplikacje do obsługi płatności mogą przekazywać obiekt methodDetails jako opcjonalny drugi argument funkcji PaymentRequestEvent.changePaymentMethod(). Ten obiekt może zawierać dowolne dane formy płatności wymagane przez sprzedawcę do przetworzenia zdarzenia zmiany.

[payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'PAYMENT_METHOD_CHANGED':
        const newMethod = e.data.paymentMethod;
        const newDetails = e.data.methodDetails;
        // Redact or check that no sensitive information is passed in
        // `newDetails`.
        // Notify the merchant of the payment method change
        details =
          await payment_request_event.changePaymentMethod(newMethod, newDetails);
      …

Gdy sprzedawca otrzyma zdarzenie paymentmethodchange z interfejsu PaymentRequest API, może zaktualizować szczegóły płatności i odpowiedzieć obiektem PaymentDetailsUpdate.

[merchant]

request.addEventListener('paymentmethodchange', e => {
  if (e.methodName === 'another-pay') {
    // Apply $10 discount for example.
    const discount = {
      label: 'special discount',
      amount: {
        currency: 'USD',
        // The value being string complies the spec
        value: '-10.00'
      }
    };
    let total = 0;
    details.displayItems.push(discount);
    for (let item of details.displayItems) {
     total += parseFloat(item.amount.value);
    }
    // Convert the number back to string
    details.total.amount.value = total.toString();
  }
  // Pass a promise to `updateWith()` and send updated payment details
  e.updateWith(details);
});

Gdy sprzedawca odpowie, obietnica zwróceniaPaymentRequestEvent.changePaymentMethod()będzie rozwiązywać się z obiektemPaymentRequestDetailsUpdate.

[payment handler] service-worker.js

…
        // Notify the merchant of the payment method change
        details = await payment_request_event.changePaymentMethod(newMethod, newDetails);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

Użyj obiektu, aby zaktualizować interfejs użytkownika. Zobacz Odzwierciedlanie zaktualizowanych danych do płatności.

Informowanie sprzedawcy o zmianie adresu dostawy

Aplikacje do płatności mogą przekazywać sprzedawcy adres dostawy klienta w ramach transakcji płatności.

Jest to przydatne dla sprzedawców, ponieważ mogą oni zlecić zbieranie adresów aplikacjom do płatności. Ponieważ dane adresu będą podawane w standardowym formacie danych, sprzedawca może oczekiwać, że adresy dostawy będą miały spójną strukturę.

Klienci mogą też zarejestrować adres w ulubionej aplikacji do płatności i używać go w przypadku różnych sprzedawców.

Aplikacje do płatności mogą udostępniać interfejs użytkownika do edytowania adresu dostawy lub do wybierania wcześniej zarejestrowanych informacji o adresie klienta w ramach transakcji płatności. Gdy adres dostawy zostanie tymczasowo określony, aplikacja do płatności może poinformować sprzedawcę o usuniętej informacji o adresie. Daje to sprzedawcom wiele korzyści:

• Sprzedawca może określić, czy klient spełnia regionalne ograniczenia dotyczące dostawy produktu (np. tylko na terenie kraju).
• Sprzedawca może zmienić listę opcji dostawy w zależności od regionu adresu dostawy (np. międzynarodowa przesyłka standardowa lub ekspresowa).
• Sprzedawca może zastosować nowy koszt dostawy na podstawie adresu i zaktualizować łączną cenę.

Dzięki interfejsowi Payment Handler API aplikacja do płatności może wysłać do sprzedawcy zdarzenie „zmianę adresu dostawy” z workera usługi, aby powiadomić o nowym adresie dostawy. Usługa robocza powinna wywoływać PaymentRequestEvent.changeShippingAddress()z użyciem obiektu new address.

[payment handler] service-worker.js

...
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_ADDRESS_CHANGED':
        const newAddress = e.data.shippingAddress;
        details =
          await payment_request_event.changeShippingAddress(newAddress);
      …

Sprzedawca otrzyma zdarzenie shippingaddresschange z interfejsu PaymentRequest API, aby mógł odpowiedzieć zaktualizowanym PaymentDetailsUpdate.

[merchant]

request.addEventListener('shippingaddresschange', e => {
  // Read the updated shipping address and update the request.
  const addr = request.shippingAddress;
  const details = getPaymentDetailsFromShippingAddress(addr);
  // `updateWith()` sends back updated payment details
  e.updateWith(details);
});

Gdy sprzedawca odpowie, obietnica zwrócona zPaymentRequestEvent.changeShippingAddress() zostanie rozwiązana za pomocą obiektu PaymentRequestDetailsUpdate.

[payment handler] service-worker.js

…
        // Notify the merchant of the shipping address change
        details = await payment_request_event.changeShippingAddress(newAddress);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

Użyj obiektu, aby zaktualizować interfejs użytkownika. Zobacz Odzwierciedlanie zaktualizowanych danych do płatności.

Informowanie sprzedawcy o zmianie opcji dostawy

Opcje dostawy to metody dostawy, których sprzedawcy używają do wysyłania zakupionych produktów do klienta. Typowe opcje dostawy:

• Bezpłatna dostawa
• Przesyłka ekspresowa
• wysyłka za granicę
• Przesyłka międzynarodowa Premium

Każdy z nich wiąże się z odrębnym kosztem. Zwykle szybsze metody i opcje są droższe.

Sprzedawcy korzystający z interfejsu Payment Request API mogą zlecić wybór aplikacji do płatności. Aplikacja do płatności może wykorzystać te informacje do tworzenia interfejsu użytkownika i umożliwić klientowi wybranie opcji dostawy.

Lista opcji dostawy określona w interfejsie API żądania płatności sprzedawcy jest propagowana do workera usługi aplikacji do płatności jako właściwość PaymentRequestEvent.

[merchant]

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: { transactionId: '****' }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  shippingOptions: [{
    id: 'standard',
    label: 'Standard',
    amount: { value: '0.00', currency: 'USD' },
    selected: true
  }, {
    id: 'express',
    label: 'Express',
    amount: { value: '5.00', currency: 'USD' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {  requestShipping: true });

Aplikacja do płatności może poinformować sprzedawcę, którą opcję dostawy wybrał klient. Jest to ważne zarówno dla sprzedawcy, jak i dla klienta, ponieważ zmiana opcji dostawy powoduje również zmianę łącznej ceny. Sprzedawca musi zostać poinformowany o najnowszej cenie na potrzeby weryfikacji płatności, a klient musi być świadomy tej zmiany.

Dzięki interfejsowi Payment Handler API aplikacja płatnicza może wysłać do sprzedawcy z użyciem service workera zdarzenie „zmianę opcji dostawy”. Usługa powinna wywołać PaymentRequestEvent.changeShippingOption()z nowym identyfikatorem opcji dostawy.

[payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_OPTION_CHANGED':
        const newOption = e.data.shippingOptionId;
        details =
          await payment_request_event.changeShippingOption(newOption);
      …

Sprzedawca otrzyma zdarzenie shippingoptionchange z interfejsu PaymentRequest API. Sprzedawca powinien użyć tych informacji do zaktualizowania łącznej ceny, a następnie odpowiedzieć, podając zaktualizowany PaymentDetailsUpdate.

[merchant]

request.addEventListener('shippingoptionchange', e => {
  // selected shipping option
  const shippingOption = request.shippingOption;
  const newTotal = {
    currency: 'USD',
    label: 'Total due',
    value: calculateNewTotal(shippingOption),
  };
  // `updateWith()` sends back updated payment details
  e.updateWith({ total: newTotal });
});

Gdy sprzedawca odpowie, obietnica zwróceniaPaymentRequestEvent.changeShippingOption()będzie rozwiązywać się z obiektemPaymentRequestDetailsUpdate.

[payment handler] service-worker.js

…
        // Notify the merchant of the shipping option change
        details = await payment_request_event.changeShippingOption(newOption);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

Użyj obiektu, aby zaktualizować interfejs użytkownika. Zobacz Odzwierciedlanie zaktualizowanych danych do płatności.

odzwierciedlać zaktualizowane dane do płatności;

Gdy sprzedawca skończy aktualizować szczegóły płatności, obietnice zwrócone z .changePaymentMethod(), .changeShippingAddress() i .changeShippingOption() zostaną rozwiązane za pomocą wspólnego obiektu PaymentRequestDetailsUpdate. Za pomocą wyniku interfejs płatności może zaktualizować łączną cenę i opcje dostawy.

Sprzedawcy mogą zwracać błędy z kilku powodów:

• forma płatności nie jest akceptowana;
• adres dostawy znajduje się poza obsługiwanymi regionami.
• Adres dostawy zawiera nieprawidłowe informacje.
• opcja dostawy nie jest dostępna dla podanego adresu dostawy lub z innego powodu.

Aby określić stan błędu, użyj tych właściwości:

• error: czytelny dla człowieka ciąg tekstowy błędu. Jest to najlepszy ciąg znaków do wyświetlania klientom.
• shippingAddressErrors: AddressErrors obiekt zawierający szczegółowy ciąg znaków błędu dla każdej właściwości adresu. Jest to przydatne, jeśli chcesz otworzyć formularz, który umożliwia klientowi edytowanie adresu, i musisz wskazać mu bezpośrednio nieprawidłowe pola.
• paymentMethodErrors: obiekt błędu związany z formą płatności. Możesz poprosić sprzedawców o przesłanie sformatowanego błędu, ale autorzy specyfikacji Web Payments zalecają, aby pozostawić go w postaci prostego ciągu znaków.

Przykładowy kod

Większość przykładowych kodów w tym dokumencie to fragmenty działającej przykładowej aplikacji:

https://paymenthandler-demo.glitch.me

[payment handler] service worker

[payment handler] frontend

Aby to zrobić:

1. Otwórz stronę https://paymentrequest-demo.glitch.me/.
2. Przewiń do dołu strony.
3. Naciśnij przycisk Dodaj formę płatności.
4. W polu Identyfikator formy płatności wpisz https://paymenthandler-demo.glitch.me.
5. Kliknij przycisk Zapłać obok pola.