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ę użytkowników.

Eiji Kitamura

gdy internetowa aplikacja płatnicza otrzyma żądanie płatności i zainicjuje płatność transakcja Service Worker jako centrum komunikacji między sprzedawcą a aplikacją płatniczą. Ten post wyjaśnia, jak aplikacja płatnicza może przekazać informacje o formie płatności; adresu dostawy lub danych kontaktowych sprzedawcy za pomocą mechanizmu Service Worker.

Poinformuj sprzedawcę o zmianie formy płatności

Aplikacje płatnicze mogą obsługiwać wiele instrumentów płatniczych za pomocą różnych form płatności.

Na przykład w tabeli powyżej, internetowy portfel klienta A ma dwa punkty i zarejestrowano 1 konto bankowe. W tym przypadku aplikacja obsługuje 3 elementy, instrumenty płatnicze (****1234, ****4242, ******123) i 2 płatności (wystawca karty kredytowej 1 i bank X). Przy transakcjach płatności aplikacja pozwala klientowi wybrać jeden z instrumentów płatniczych i użyć go do zapłaty sprzedawcy.

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

Za pomocą interfejsu Payment Handler API aplikacja płatnicza może wysłać „zmianę formy płatności”. wysyłane do sprzedawcy przez skrypt service worker w celu powiadomienia nowej formy płatności Skrypt service worker powinien wywołać PaymentRequestEvent.changePaymentMethod() na nową formę płatności i informacjami o nich.

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

[moduł do 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 płatności request API, może zaktualizować dane do płatności i wysłać odpowiedź PaymentDetailsUpdate obiektu.

[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);
});

W odpowiedzi sprzedawcy PaymentRequestEvent.changePaymentMethod() zostanie rozwiązane przy użyciu PaymentRequestDetailsUpdate obiektu.

[moduł do 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;
…

Zaktualizuj interfejs użytkownika we frontendzie za pomocą obiektu. Patrz sekcja Odzwierciedlenie zmian dane do płatności.

Poinformuj sprzedawcę o zmianie adresu dostawy

Aplikacje do wykonywania płatności mogą w ramach tych działań przekazywać sprzedawcy adres dostawy klienta transakcji płatności.

Jest to przydatne dla sprzedawców, ponieważ mogą przekazać zbieranie adresów do: aplikacje płatnicze. A ponieważ dane adresowe będą udostępniane standardowo format danych, sprzedawca może spodziewać się adresów dostawy o spójnej strukturze.

Ponadto klienci mogą zarejestrować swoje dane adresowe w preferowanej aplikacji płatniczej i używania jej u różnych sprzedawców.

Aplikacje do wykonywania płatności mogą zawierać interfejs umożliwiający edycję adresu dostawy wcześniej zarejestrowanych danych adresowych klienta dokonującego płatności. Gdy adres dostawy zostanie tymczasowo określony, aplikacja płatnicza może zezwolić sprzedawca otrzyma usunięte informacje adresowe. Dzięki temu sprzedawcy mogą Wiele korzyści:

• Sprzedawca może określić, czy klient spełnia ograniczenia regionalne aby wysłać produkt (na przykład tylko w kraju).
• Sprzedawca może zmienić listę opcji dostawy w zależności od regionu adres dostawy (na przykład międzynarodowe zwykłe lub ekspresowe).
• 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 wysyłać „adres dostawy” zmień” zdarzenie wysyłane do sprzedawcy przez skrypt service worker w celu powiadomienia o nowej dostawie adresu. Skrypt service worker powinien wywołać PaymentRequestEvent.changeShippingAddress() z nowym adresem .

[moduł do 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 Centrum płatności Poproś o dostęp do interfejsu API w celu udzielenia odpowiedzi za pomocą 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 odpowiada, PaymentRequestEvent.changeShippingAddress() zostanie rozwiązane przy użyciu PaymentRequestDetailsUpdate obiektu.

[moduł do 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;
…

Zaktualizuj interfejs użytkownika we frontendzie za pomocą obiektu. Patrz sekcja Odzwierciedlenie zmian dane do płatności.

Poinformuj sprzedawcę o zmianie opcji wysyłki

Opcje dostawy to sposoby dostawy, z których sprzedawcy korzystają, by wysłać kupione produkty do klienta. Typowe opcje dostawy:

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

Każda z nich wiąże się z innymi kosztami. Zwykle szybsze metody lub opcje są droższe.

Sprzedawcy używający Payment Request API mogą przekazać ten wybór do płatności aplikacji. Aplikacja płatnicza może wykorzystać te informacje do stworzenia interfejsu użytkownika i pozwolić klient wybrał opcję dostawy.

Lista opcji dostawy w interfejsie Payment Request API sprzedawcy to przekazywane 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 klient wybrane. Jest to ważne zarówno dla sprzedawcy, jak i dla klienta, ponieważ zmiana opcji dostawy powoduje też zmianę łącznej ceny. Sprzedawca potrzebuje aby otrzymać informację o ostatniej cenie weryfikacji płatności oraz klient musi być świadomy tej zmiany.

Dzięki interfejsowi Payment Handler API aplikacja płatnicza może wysyłać „opcję dostawy” zmień” zdarzenia wysyłanego do sprzedawcy przez skrypt service worker. Skrypt service worker powinien wywołać PaymentRequestEvent.changeShippingOption() podając nowy identyfikator opcji dostawy.

[moduł do 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 Centrum płatności Interfejs API żądań. Sprzedawca powinien użyć tych informacji, aby zaktualizować łączną cenę a następnie odpowiedzieć, 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 });
});

W odpowiedzi sprzedawcy PaymentRequestEvent.changeShippingOption() zostanie rozwiązane przy użyciu PaymentRequestDetailsUpdate obiektu.

[moduł do 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;
…

Zaktualizuj interfejs użytkownika we frontendzie za pomocą obiektu. Patrz sekcja Odzwierciedlenie zmian dane do płatności.

zawierać zaktualizowane dane do płatności;

Obietnice zwrócone, gdy sprzedawca zakończy aktualizowanie danych do płatności od .changePaymentMethod(), .changeShippingAddress() i .changeShippingOption() zostanie rozwiązany przy użyciu typowej przyczyny PaymentRequestDetailsUpdate obiektu. Moduł obsługi płatności może użyć wyniku, aby odzwierciedlić zaktualizowaną cenę łączną oraz opcje dostawy.

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

• Forma płatności nie jest akceptowana.
• Adres dostawy znajduje się poza obsługiwanym regionem.
• Adres dostawy zawiera nieprawidłowe informacje.
• W przypadku podanego adresu nie można wybrać opcji 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 jest najlepszy ciąg znaków do wyświetlenia do klientów.
• shippingAddressErrors: AddressErrors który zawiera szczegółowy ciąg znaków błędu dla każdej właściwości adresu. To jest przydatne, jeśli chcesz otworzyć formularz, za pomocą którego klient będzie mógł edytować adres a Ty musisz wskazać im nieprawidłowe pola.
• paymentMethodErrors: obiekt błędu związanego z formą płatności. Możesz zapytać sprzedawcy, aby podać błąd strukturalny, ale autorzy specyfikacji Płatności internetowych najlepiej jest to prosty ciąg znaków.

Przykładowy kod

Większość przykładowych kodów widocznych w tym dokumencie to fragmenty działająca przykładowa aplikacja:

https://paymenthandler-demo.glitch.me

Skrypt service worker

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

Aby wypróbować tę funkcję:

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