Gestire i dati di pagamento facoltativi con un service worker

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

Eiji Kitamura

Quando un'app per pagamenti basata sul web riceve una richiesta di pagamento ed esegue un pagamento transazione, il service worker agirà come hub di comunicazione tra il commerciante e l'app di pagamento. Questo post spiega in che modo un'app di pagamento può trasferire informazioni sul metodo di pagamento, l'indirizzo di spedizione o i dati di contatto del commerciante presso un service worker.

Informare il commerciante della modifica del metodo di pagamento

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

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

L'app di pagamento può comunicare al commerciante quale metodo di pagamento sceglie il cliente selezionata prima di inviare la risposta di pagamento completa. Ciò è utile quando il commerciante vuole pubblicare una campagna scontata per uno specifico brand di metodo di pagamento, ad esempio.

Con l'API Payment Gestori, l'app per i pagamenti può inviare una "modifica del metodo di pagamento" al commerciante tramite un service worker per informare il nuovo metodo di pagamento identificativo dell'utente. Il service worker deve richiamare PaymentRequestEvent.changePaymentMethod() con il nuovo metodo di pagamento informazioni.

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

[gestore dei pagamenti] 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 dalla di richiesta API, può aggiornare i dati di pagamento e rispondere con un PaymentDetailsUpdate .

[commerciante]

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 che PaymentRequestEvent.changePaymentMethod() viene restituito come risultato PaymentRequestDetailsUpdate .

[gestore dei pagamenti] 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 Riflettere la versione dati di pagamento.

Informare il commerciante in merito a un cambio dell'indirizzo di spedizione

Le app di pagamento possono fornire al commerciante l'indirizzo di spedizione di un cliente come parte di una transazione di pagamento.

È utile per i commercianti perché possono delegare la raccolta degli indirizzi a app di pagamento. Inoltre, poiché i dati degli indirizzi saranno forniti nella formato dei dati, il commerciante riceverà gli indirizzi di spedizione in una struttura coerente.

Inoltre, i clienti possono registrare i dati dell'indirizzo l'app di pagamento preferita e riutilizzarla per diversi commercianti.

Le app di pagamento possono fornire un'interfaccia utente per modificare un indirizzo di spedizione o per selezionarlo l'indirizzo preregistrato del cliente in una transazione di pagamento. Quando viene determinato temporaneamente un indirizzo di spedizione, l'app per pagamenti può consentire il commerciante sia a conoscenza dei dati dell'indirizzo oscurati. Ciò offre ai commercianti più vantaggi:

• Un commerciante può determinare se il cliente soddisfa le limitazioni regionali per spedire l'articolo (ad es. solo nazionale).
• Un commerciante può modificare l'elenco delle opzioni di spedizione in base alla regione del indirizzo di spedizione (ad es. internazionale regolare o espressa).
• Un commerciante può applicare il nuovo costo di spedizione in base all'indirizzo e aggiornare il prezzo totale.

Con l'API Payment Gestori, l'app di pagamento può inviare un "indirizzo di spedizione cambia" l'evento al commerciante dal service worker per notificare la nuova spedizione . Il service worker deve richiamare PaymentRequestEvent.changeShippingAddress() con il nuovo indirizzo ..

[gestore dei pagamenti] 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);
      …

Il commerciante riceverà un evento shippingaddresschange dall'account l'API Request (per le richieste di assistenza) in modo che possa rispondere con la versione aggiornata di PaymentDetailsUpdate.

[commerciante]

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() viene restituito come risultato PaymentRequestDetailsUpdate .

[gestore dei pagamenti] 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 Riflettere la versione dati di pagamento.

Informare il commerciante di una modifica dell'opzione di spedizione

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

• Spedizione gratuita
• Spedizione espressa
• Spedizione internazionale
• Spedizione internazionale premium

Ognuno ha il proprio costo. In genere, i metodi/le opzioni più veloci sono più costosi.

I commercianti che utilizzano l'API Payment Request possono delegare questa selezione a un pagamento dell'app. L'app di pagamento può utilizzare le informazioni per creare un'interfaccia utente e consentire il cliente sceglie un'opzione di spedizione.

L'elenco delle opzioni di spedizione specificate nell'API Payment Request del commerciante è propagati al service worker dell'app per pagamenti come una proprietà PaymentRequestEvent.

[commerciante]

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 di pagamento può comunicare al commerciante quale opzione di spedizione sceglie al cliente selezionato. Questo è importante sia per il commerciante che per il cliente perché la modifica dell'opzione di spedizione modifica anche il prezzo totale. Il commerciante ha bisogno di essere informato del prezzo più recente per la verifica dei pagamenti e di il cliente deve essere a conoscenza del cambiamento.

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

[gestore dei pagamenti] 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'account API di richiesta. Il commerciante deve utilizzare queste informazioni per aggiornare il prezzo totale e rispondere con i dati PaymentDetailsUpdate

[commerciante]

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 che PaymentRequestEvent.changeShippingOption() viene restituito come risultato PaymentRequestDetailsUpdate .

[gestore dei pagamenti] 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 Riflettere la versione dati di pagamento.

Indica i dati di pagamento aggiornati

Una volta che il commerciante ha terminato di aggiornare i dati di pagamento, le promesse vengono restituite da .changePaymentMethod(), .changeShippingAddress() e .changeShippingOption() verrà risolto con un PaymentRequestDetailsUpdate . Il gestore dei pagamenti può utilizzare il risultato per riflettere il prezzo totale aggiornato e le opzioni di spedizione nell'interfaccia utente.

I commercianti possono restituire errori per diversi motivi:

• Il metodo di pagamento non è accettabile.
• L'indirizzo di spedizione non si trova nelle regioni supportate.
• L'indirizzo di spedizione contiene informazioni non valide.
• Non è possibile selezionare l'opzione di spedizione per l'indirizzo di spedizione fornito o per un altro motivo.

Per riflettere lo stato di errore, utilizza le seguenti proprietà:

• error: stringa di errore leggibile. Questa è la stringa migliore da visualizzare ai clienti.
• shippingAddressErrors: AddressErrors che contiene una 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 indirizzarli direttamente ai campi non validi.
• paymentMethodErrors: oggetto di errore specifico per il metodo di pagamento. Puoi chiedere ai commercianti di fornire un errore strutturato, ma gli autori della specifica di Web Payments consigliamo di usarla come stringa semplice.

Codice di esempio

La maggior parte dei codici di esempio consultati in questo documento sono estratti da quanto segue: esempio di app funzionante:

https://paymenthandler-demo.glitch.me

Service worker [gestore dei pagamenti]

Frontend [gestore dei pagamenti]

Per provarlo:

1. Vai alla pagina https://paymentrequest-demo.glitch.me/.
2. Vai alla parte inferiore della pagina.
3. Premi il pulsante Aggiungi un pagamento.
4. Inserisci https://paymenthandler-demo.glitch.me nel campo Identificatore metodo di pagamento.
5. Premi il pulsante Paga accanto al campo.