Gestire i dati di pagamento facoltativi con un service worker

Come adattare la tua app per pagamenti basata sul web a Web Payments e offrire un'esperienza utente migliore ai clienti.

Eiji Kitamura

Una volta che un'app per pagamenti basata sul web riceve una richiesta di pagamento e avvia una transazione di pagamento, il service worker fungerà da hub per la comunicazione tra il commerciante e l'app per pagamenti. Questo post spiega come un'app per pagamenti può trasmettere al commerciante informazioni sul metodo di pagamento, sull'indirizzo di spedizione o sui dati di contatto utilizzando un service worker.

Informare il commerciante

È importante informare il commerciante delle seguenti modifiche.

Modifica del metodo di pagamento

Le app per pagamenti possono supportare più strumenti di pagamento con metodi di pagamento diversi.

Ad esempio, nella tabella precedente, il portafoglio basato sul web del Cliente A ha due carte di credito e un conto bancario registrati. In questo caso, l'app gestisce tre strumenti di pagamento (****1234, ****4242, ******123) e due metodi di pagamento (Emittente della carta di credito 1 e Banca X). In una transazione di pagamento, l'app per pagamenti può consentire al cliente di scegliere uno degli strumenti di pagamento e utilizzarlo per pagare il commerciante.

L'app per pagamenti può comunicare al commerciante il metodo di pagamento scelto dal cliente prima di inviare la risposta di pagamento completa. Ciò è utile, ad esempio, quando il commerciante vuole pubblicare una campagna di sconti per un brand di un metodo di pagamento specifico.

Con l'API Payment Handler basata sul web, l'app per pagamenti può inviare un evento "payment method change" al commerciante tramite un service worker per comunicare il nuovo identificatore del metodo di pagamento. Il service worker deve richiamare PaymentRequestEvent.changePaymentMethod() con le informazioni sul nuovo metodo di pagamento.

Le app per pagamenti possono passare un oggetto methodDetails come secondo argomento facoltativo per PaymentRequestEvent.changePaymentMethod(). Questo oggetto può contenere dettagli arbitrari sul metodo di pagamento richiesti dal commerciante per elaborare l'evento di modifica.

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

Quando il commerciante riceve un evento paymentmethodchange dall'API Payment Request, può aggiornare i dettagli di pagamento e rispondere con un oggetto 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);
});

Quando il commerciante risponde, la promessa restituita da PaymentRequestEvent.changePaymentMethod() verrà risolta con un oggetto PaymentRequestDetailsUpdate.

[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;
…

Utilizza l'oggetto per aggiornare la UI sul frontend. Consulta la sezione Rifletti i dati di pagamento aggiornati.

Modifica dell'indirizzo di spedizione

Le app per pagamenti possono fornire l'indirizzo di spedizione di un cliente al commerciante nell'ambito di una transazione di pagamento.

Questo è utile per i commercianti perché possono delegare la raccolta degli indirizzi alle app per pagamenti. Inoltre, poiché i dati dell'indirizzo verranno forniti nel formato dei dati standard, il commerciante può aspettarsi di ricevere gli indirizzi di spedizione in una struttura coerente.

Inoltre, i clienti possono registrare i dati relativi al proprio indirizzo nell'app per pagamenti preferita e riutilizzarli per diversi commercianti.

Le app per pagamenti possono fornire una UI per modificare un indirizzo di spedizione o per selezionare i dati dell'indirizzo preregistrati per il cliente in una transazione di pagamento. Quando un indirizzo di spedizione viene determinato temporaneamente, l'app per pagamenti può comunicare al commerciante le informazioni sull'indirizzo oscurato. Questo offre ai commercianti diversi vantaggi:

• Un commerciante può determinare se il cliente soddisfa la limitazione regionale per la spedizione dell'articolo (ad esempio, solo spedizione nazionale).
• Un commerciante può modificare l'elenco delle opzioni di spedizione in base alla regione dell'indirizzo di spedizione (ad esempio, spedizione internazionale standard o rapida).
• Un commerciante può applicare il nuovo costo di spedizione in base all'indirizzo e aggiornare il prezzo totale.

Con l'API Payment Handler basata sul web, l'app per pagamenti può inviare un evento "cambio di indirizzo di spedizione" al commerciante dal service worker per comunicare il nuovo indirizzo di spedizione. Il service worker deve richiamare PaymentRequestEvent.changeShippingAddress() con il nuovo oggetto indirizzo.

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

Termine chiave: indirizzo oscurato. In questo caso, non è necessario comunicare l'indirizzo di spedizione completo al commerciante e si rischia di compromettere la privacy dei clienti. Il commerciante riceve solo le parti dell'indirizzo necessarie per determinare il costo di spedizione. In particolare, il browser cancellerà i campi organization, phone, recipient, addressLine dall'indirizzo fornito dall'app per pagamenti prima di generare l'evento shippingaddresschange nel DOM del commerciante.

Il commerciante riceverà un evento shippingaddresschange dall'API Payment Request, in modo da poter rispondere con l'oggetto PaymentDetailsUpdate aggiornato.

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

Quando il commerciante risponde, la promessa PaymentRequestEvent.changeShippingAddress() restituita verrà risolta con un oggetto 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;
…

Utilizza l'oggetto per aggiornare la UI sul frontend. Consulta la sezione Rifletti i dati di pagamento aggiornati.

Informare il commerciante di una modifica dell'opzione di spedizione

Le opzioni di spedizione sono i metodi di consegna utilizzati dai commercianti per spedire gli articoli acquistati a un cliente. Le opzioni di spedizione tipiche includono:

• Spedizione gratuita
• Spedizione rapida
• Spedizione internazionale
• Spedizione internazionale premium

Ognuna ha un costo diverso. In genere, i metodi e le opzioni più veloci sono più costosi.

I commercianti che utilizzano l'API Payment Request possono delegare questa selezione a un'app per pagamenti. L'app per pagamenti può utilizzare le informazioni per creare una UI e consentire al cliente di scegliere un'opzione di spedizione.

L'elenco delle opzioni di spedizione specificate nell'API Payment Request del commerciante viene propagato al service worker dell'app per pagamenti come proprietà di 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 });

L'app per pagamenti può comunicare al commerciante l'opzione di spedizione scelta dal cliente. Questo è importante sia per il commerciante sia per il cliente, perché la modifica dell'opzione di spedizione modifica anche il prezzo totale. Il commerciante deve essere informato del prezzo più recente per la verifica del pagamento in un secondo momento e anche il cliente deve essere a conoscenza della modifica.

Con l'API Payment Handler, l'app per pagamenti può inviare un evento "shipping option change" al commerciante dal service worker. Il service worker deve richiamare PaymentRequestEvent.changeShippingOption() con il nuovo ID opzione di spedizione.

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

Il commerciante riceverà un evento shippingoptionchange dall'API Payment Request. Il commerciante deve utilizzare le informazioni per aggiornare il prezzo totale e poi rispondere con l'oggetto PaymentDetailsUpdate aggiornato.

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

Quando il commerciante risponde, la promessa restituita da PaymentRequestEvent.changeShippingOption() verrà risolta con un oggetto PaymentRequestDetailsUpdate.

[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;
…

Utilizza l'oggetto per aggiornare la UI sul frontend. Consulta la sezione Rifletti i dati di pagamento aggiornati.

Riflettere i dati di pagamento aggiornati

Una volta che il commerciante ha terminato di aggiornare i dettagli di pagamento, le promise restituite da .changePaymentMethod(), .changeShippingAddress() e .changeShippingOption() verranno risolte con un oggetto PaymentRequestDetailsUpdate comune. Il gestore dei pagamenti può utilizzare il risultato per mostrare il prezzo totale aggiornato e le opzioni di spedizione nell'interfaccia utente.

I commercianti potrebbero restituire errori per alcuni motivi:

• Il metodo di pagamento non è accettabile.
• L'indirizzo di spedizione non rientra nelle regioni supportate.
• L'indirizzo di spedizione contiene informazioni non valide.
• L'opzione di spedizione non è selezionabile per l'indirizzo di spedizione fornito o per qualche altro motivo.

Utilizza le seguenti proprietà per riflettere lo stato di errore:

• error: stringa di errore leggibile. Questa è la stringa migliore da mostrare ai clienti.
• shippingAddressErrors: AddressErrors oggetto che contiene la stringa di errore dettagliata per proprietà dell'indirizzo. Questo è utile se vuoi aprire un modulo che consenta al cliente di modificare il proprio indirizzo e devi indirizzarlo direttamente ai campi non validi.
• paymentMethodErrors: oggetto di errore specifico del metodo di pagamento. Puoi chiedere ai commercianti di fornire un errore strutturato, ma gli autori della specifica Web Payments consigliano di mantenerlo come una stringa semplice.