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

Jak dostosować internetową aplikację płatniczą do płatności internetowych i zapewnić klientom większą wygodę.

Eiji Kitamura

Gdy internetowa aplikacja płatnicza otrzyma żądanie płatności i zainicjuje transakcję płatności, skrypt service worker będzie działać jako centrum komunikacji między sprzedawcą a aplikacją płatniczą. Ten post wyjaśnia, jak aplikacja płatnicza może przekazać sprzedawcy informacje o formie płatności, adresie dostawy lub danych kontaktowych do sprzedawcy za pomocą skryptu service worker.

Powiadomienie sprzedawcy o zmianie formy płatności

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

W tabeli powyżej w portfelu internetowym Klienta A są zarejestrowane dwie karty kredytowe i jedno konto bankowe. W tym przypadku aplikacja obsługuje 3 instrumenty płatności (****1234, ****4242, ******123) i 2 formy płatności (wystawca karty kredytowej 1 i bank X). W przypadku transakcji płatności aplikacja płatnicza może pozwolić klientowi wybrać jeden z instrumentów płatniczych i użyć go do opłacenia zamówienia sprzedawcy.

Przed wysłaniem pełnej odpowiedzi na płatność aplikacja płatnicza może poinformować sprzedawcę, którą formę płatności wybrał klient. Jest to przydatne, gdy sprzedawca chce przeprowadzić kampanię rabatową dla określonej marki formy płatności.

Dzięki interfejsowi Payment Handler API aplikacja płatnicza może za pomocą skryptu service worker wysłać do sprzedawcy zdarzenie „zmiana formy płatności”, by powiadomić go o nowym identyfikatorze formy płatności. Skrypt service worker powinien wywołać PaymentRequestEvent.changePaymentMethod() z nowymi informacjami o formie płatności.

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

[moduł obsługi płatności] 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 PaymentRequest API, może zaktualizować dane do płatności i odpowiedzieć za pomocą obiektu PaymentDetailsUpdate.

[sprzedawca]

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ócona przez usługę PaymentRequestEvent.changePaymentMethod() zniknie z obiektem PaymentRequestDetailsUpdate.

[moduł obsługi płatności] 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;
…

Ten obiekt pozwala zaktualizować interfejs użytkownika w frontendzie. Zapoznaj się z sekcją Uwzględnianie zaktualizowanych danych płatności.

Poinformuj sprzedawcę o zmianie adresu dostawy

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

Jest to przydatne dla sprzedawców, ponieważ mogą delegować zbieranie adresów aplikacjom do płatności. A ponieważ dane adresowe będą udostępniane w standardowym formacie danych, sprzedawca może spodziewać się adresów dostawy o spójnej strukturze.

Klienci mogą też zarejestrować dane adresowe w preferowanej aplikacji do płatności i używać ich u różnych sprzedawców.

Aplikacje płatnicze mogą udostępniać interfejs umożliwiający edytowanie adresu dostawy lub wybieranie wcześniej zarejestrowanych danych adresowych klienta w przypadku transakcji płatności. Gdy adres dostawy jest tymczasowo określony, aplikacja płatnicza może powiadomić sprzedawcę o usuniętych danych. Dzięki temu sprzedawcy mają wiele korzyści:

• Sprzedawca może określić, czy klient spełnia wymagania regionalne dotyczące wysyłki produktu (np. tylko w kraju).
• Sprzedawca może zmienić listę opcji dostawy w zależności od regionu podanego w adresie dostawy (np. międzynarodowy 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 płatnicza może wysłać do sprzedawcy zdarzenie „zmiana adresu dostawy”, aby powiadomić o nowym adresie dostawy. Skrypt service worker powinien wywołać metodę PaymentRequestEvent.changeShippingAddress() z nowym obiektem adresu.

[moduł obsługi płatności] 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 PaymentRequest API, aby móc odpowiedzieć przy użyciu zaktualizowanego PaymentDetailsUpdate.

[sprzedawca]

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, zwracana obietnica (PaymentRequestEvent.changeShippingAddress()) zakończy się z obiektem PaymentRequestDetailsUpdate.

[moduł obsługi płatności] 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;
…

Ten obiekt pozwala zaktualizować interfejs użytkownika w frontendzie. Zapoznaj się z sekcją Uwzględnianie zaktualizowanych danych płatności.

Poinformuj sprzedawcę o zmianie opcji dostawy

Opcje dostawy to metody dostawy używane przez sprzedawców do wysyłania zakupionych produktów do klienta. Typowe opcje dostawy:

• Bezpłatna dostawa
• Dostawa ekspresowa
• wysyłka za granicę
• Dostawa za granicę premium

Każda z tych opcji ma własny koszt. Zazwyczaj szybsze metody/opcje są droższe.

Sprzedawcy, którzy korzystają z Payment Request API, mogą delegować ten wybór do aplikacji płatniczej. Aplikacja płatnicza może wykorzystać te informacje do utworzenia interfejsu użytkownika i pozwolić klientowi wybrać opcję dostawy.

Lista opcji dostawy określona w interfejsie Payment Request API sprzedawcy jest udostępniana do skryptu service worker aplikacji płatniczej jako właściwość PaymentRequestEvent.

[sprzedawca]

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 płatnicza 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 też zmianę łącznej ceny. Sprzedawca musi później otrzymać informację o najnowszej cenie na potrzeby weryfikacji płatności, a klient też musi wiedzieć o zmianie.

Dzięki interfejsowi Payment Handler API aplikacja płatnicza może wysłać do sprzedawcy zdarzenie zmiany opcji dostawy z poziomu skryptu service worker. Skrypt service worker powinien wywołać metodę PaymentRequestEvent.changeShippingOption() z nowym identyfikatorem opcji dostawy.

[moduł obsługi płatności] 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 PaymentRequest API. Sprzedawca powinien wykorzystać te informacje do zaktualizowania łącznej ceny, a następnie przesłać zaktualizowaną PaymentDetailsUpdate.

[sprzedawca]

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ócona przez usługę PaymentRequestEvent.changeShippingOption() zniknie z obiektem PaymentRequestDetailsUpdate.

[moduł obsługi płatności] 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;
…

Ten obiekt pozwala zaktualizować interfejs użytkownika w frontendzie. Zapoznaj się z sekcją Uwzględnianie zaktualizowanych danych płatności.

Zapoznaj się ze zaktualizowanymi danymi do płatności.

Gdy sprzedawca ukończy aktualizowanie danych do płatności, zobowiązania zwrócone z usług .changePaymentMethod(), .changeShippingAddress() i .changeShippingOption() zakończą się wspólnym obiektem PaymentRequestDetailsUpdate. Moduł obsługi płatności może użyć wyniku, aby odzwierciedlić w interfejsie zaktualizowaną łączną cenę i opcje dostawy.

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

• Forma płatności jest nieakceptowalna.
• Adres dostawy znajduje się poza obsługiwanymi regionami.
• Adres dostawy zawiera nieprawidłowe informacje.
• Nie można wybrać opcji dostawy ze względu na podany adres dostawy lub z innego powodu.

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

• error: zrozumiały dla człowieka ciąg błędu. To najlepszy tekst do wyświetlania klientom.
• shippingAddressErrors: AddressErrors obiekt zawierający szczegółowy ciąg błędu dla każdej właściwości adresu. Jest to przydatne, gdy chcesz otworzyć formularz, który pozwala klientowi edytować adres i wskaż bezpośrednio nieprawidłowe pola.
• paymentMethodErrors: obiekt błędu związanego z formą płatności. Możesz poprosić sprzedawców o podanie uporządkowanego błędu, ale autorzy specyfikacji płatności internetowych zalecają, aby był to prosty ciąg znaków.

Przykładowy kod

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

https://paymenthandler-demo.glitch.me

[moduł obsługi płatności] skrypt service worker

[moduł obsługi płatności] frontend

Aby to zrobić:

1. Wejdź na https://paymentrequest-demo.glitch.me/.
2. Przewiń do dołu strony.
3. Kliknij Dodaj przycisk płatności.
4. Wpisz https://paymenthandler-demo.glitch.me w polu Identyfikator formy płatności.
5. Naciśnij przycisk Zapłać obok pola.