Ciclo di vita di una transazione di pagamento

Scopri come i commercianti integrano le app di pagamento e come funzionano le transazioni di pagamento con l'API Payment Request.

Eiji Kitamura

Milica Mihajlija

Le API Web Payments sono funzionalità di pagamento dedicate integrate per la prima volta nel browser. Grazie a Web Payments, l'integrazione dei commercianti con le app di pagamento è diventata più semplice, mentre l'esperienza del cliente diventa più semplice e sicura.

Per scoprire di più sui vantaggi dell'utilizzo di Web Payments, consulta Potenziare le app di pagamento con Web Payments.

Questo articolo illustra una transazione di pagamento su un sito web del commerciante e ti aiuta a capire come funziona l'integrazione dell'app di pagamento.

La procedura prevede sei passaggi:

1. Il commerciante avvia una transazione di pagamento.
2. Il commerciante mostra un pulsante di pagamento.

3. Il cliente preme il pulsante di pagamento.

   

4. Il browser avvia l'app di pagamento.

   

5. Se il cliente modifica i dettagli (ad es. le opzioni di spedizione o il suo indirizzo), il commerciante aggiorna i dettagli della transazione in base alla modifica.

   

6. Dopo che il cliente conferma l'acquisto, il commerciante convalida il pagamento e completa la transazione.

   

Passaggio 1: il commerciante avvia una transazione di pagamento

Quando un cliente decide di effettuare un acquisto, il commerciante avvia la transazione di pagamento costruendo un oggetto PaymentRequest. Questo oggetto include informazioni importanti sulla transazione:

• Metodi di pagamento accettabili e relativi dati per l'elaborazione della transazione.
• Dettagli come il prezzo totale (obbligatorio) e le informazioni sugli articoli.
• Opzioni in cui i commercianti possono richiedere informazioni di spedizione, ad esempio un indirizzo di spedizione e un'opzione di spedizione.
• I commercianti possono anche richiedere l'indirizzo di fatturazione, il nome, l'email e il numero di telefono dell'utente che effettua il pagamento.
• I commercianti possono anche includere type shipping (shipping, delivery o pickup) facoltativo in PaymentRequest. L'app di pagamento può utilizzarlo come suggerimento per visualizzare le etichette corrette nella sua UI.

const request = new PaymentRequest([{
  supportedMethods: 'https://bobpay.xyz/pay',
  data: {
    transactionId: '****'
  }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {
  requestShipping: true,
  requestBillingAddress: true,
  requestPayerEmail: true,
  requestPayerPhone: true,
  requestPayerName: true,
  shippingType: 'delivery'
});

Fornite le informazioni sulla transazione, il browser esegue un processo di rilevamento delle app di pagamento specificate nel PaymentRequest in base agli identificatori dei metodi di pagamento. In questo modo, il browser può determinare l'app di pagamento da avviare non appena il commerciante è pronto a procedere con la transazione.

Per informazioni dettagliate sul funzionamento del processo di rilevamento, consulta Configurare un metodo di pagamento.

Passaggio 2: il commerciante mostra un pulsante di pagamento

I commercianti possono supportare molti metodi di pagamento, ma devono mostrare solo i pulsanti di pagamento per quelli che un cliente può effettivamente utilizzare. Mostrare un pulsante di pagamento inutilizzabile rappresenta un'esperienza utente scadente. Se un commerciante può prevedere che un metodo di pagamento specificato nell'oggetto PaymentRequest non funzionerà per il cliente, può fornire una soluzione alternativa o non mostrare il pulsante.

Utilizzando un'istanza PaymentRequest, un commerciante può richiedere se un cliente ha disponibile l'app di pagamento.

Il cliente ha a disposizione l'app di pagamento?

Il metodo canMakePayment() di PaymentRequest restituisce true se un'app di pagamento è disponibile sul dispositivo del cliente. "Disponibile" significa che viene rilevata un'app di pagamento che supporta il metodo di pagamento e che è installata l'app di pagamento specifica della piattaforma o che l'app di pagamento basata sul web è pronta per la registrazione.

const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
  // Fallback to other means of payment or hide the button.
}

Passaggio 3: il cliente preme il pulsante di pagamento

Quando il cliente preme il pulsante di pagamento, il commerciante chiama il metodo show() dell'istanza PaymentRequest, che attiva immediatamente il lancio della UI di pagamento.

Se il prezzo totale finale è impostato in modo dinamico (ad esempio, recuperato da un server), il commerciante può posticipare il lancio dell'interfaccia utente di pagamento fino a quando il totale non è conosciuto.

Posticipazione del lancio dell'interfaccia utente di pagamento

Dai un'occhiata a una demo del rifiuto della UI di pagamento fino a quando non viene determinato il prezzo totale finale.

Per posticipare l'interfaccia utente di pagamento, il commerciante passa una promessa al metodo show(). Il browser mostrerà un indicatore di caricamento fino a quando la promessa non sarà risolta e la transazione non sarà pronta per iniziare.

const getTotalAmount = async () => {
  // Fetch the total amount from the server, etc.
};

try {
  const result = await request.show(getTotalAmount());
  // Process the result…
} catch(e) {
  handleError(e);
}

Se non è specificata alcuna promessa come argomento per show(), il browser avvierà la UI di pagamento immediatamente.

Passaggio 4: il browser avvia l'app di pagamento

Il browser può avviare un'app di pagamento specifica per la piattaforma o basata sul web. Scopri di più su come Chrome determina quale app di pagamento avviare.

La modalità di creazione dell'app di pagamento dipende in gran parte dallo sviluppatore, ma gli eventi emessi dal commerciante e verso di lui, nonché la struttura dei dati trasmessi con questi eventi, sono standardizzati.

All'avvio, l'app di pagamento riceve le informazioni sulla transazione passate all'oggetto PaymentRequest nel Passaggio 1, che includono quanto segue:

• Dati del metodo di pagamento
• Prezzo totale
• Opzioni di pagamento

L'app di pagamento utilizza le informazioni sulla transazione per etichettare la sua interfaccia utente.

Passaggio 5: in che modo un commerciante può aggiornare i dettagli della transazione in base alle azioni del cliente

I clienti hanno la possibilità di modificare i dettagli della transazione, ad esempio il metodo di pagamento e l'opzione di spedizione, nell'app di pagamento. Mentre il cliente apporta le modifiche, il commerciante riceve gli eventi di modifica e aggiorna i dettagli della transazione.

Un commerciante può ricevere quattro tipi di eventi:

• Evento di modifica del metodo di pagamento
• Evento di modifica dell'indirizzo di spedizione
• Evento di modifica dell'opzione di spedizione
• Evento di convalida del commerciante

Evento di modifica del metodo di pagamento

Un'app di pagamento può supportare più metodi di pagamento e un commerciante può offrire un sconto speciale a seconda della selezione del cliente. Per coprire questo caso d'uso, l'evento di modifica del metodo di pagamento può informare il commerciante del nuovo metodo di pagamento in modo che possa aggiornare il prezzo totale con lo sconto e restituirlo all'app di pagamento.

request.addEventListener('paymentmethodchange', e => {
  e.updateWith({
    // Add discount etc.
  });
});

Evento di modifica dell'indirizzo di spedizione

Un'app di pagamento può facoltativamente fornire l'indirizzo di spedizione del cliente. Questo è conveniente per i clienti perché non devono inserire manualmente i dettagli in un modulo e possono memorizzare il proprio indirizzo di spedizione nelle proprie app di pagamento preferite, anziché su più siti web di commercianti diversi.

Se un cliente aggiorna il proprio indirizzo di spedizione in un'app di pagamento dopo l'avvio della transazione, al commerciante verrà inviato un evento 'shippingaddresschange'. Questo evento aiuta il commerciante a determinare il costo di spedizione in base al nuovo indirizzo, ad aggiornare il prezzo totale e a restituirlo all'app di pagamento.

request.addEventListener('shippingaddresschange', e => {
  e.updateWith({
    // Update the details
  });
});

Se il commerciante non può effettuare la spedizione all'indirizzo aggiornato, può fornire un messaggio di errore aggiungendo un parametro di errore ai dettagli della transazione restituiti all'app di pagamento.

Evento di modifica dell'opzione di spedizione

Un commerciante può offrire al cliente più opzioni di spedizione e può delegare questa scelta all'app di pagamento. Le opzioni di spedizione vengono visualizzate sotto forma di elenco di prezzi e nomi di servizi tra cui il cliente può scegliere. Ad esempio:

• Spedizione standard - Gratuita
• Spedizione espressa - 5 $

Quando un cliente aggiorna l'opzione di spedizione in un'app di pagamento, al commerciante viene inviato un evento 'shippingoptionchange'. Il commerciante può quindi determinare il costo di spedizione, aggiornare il prezzo totale e restituirlo all'app di pagamento.

request.addEventListener('shippingoptionchange', e => {
  e.updateWith({
    // Update the details
  });
});

Il commerciante può modificare dinamicamente le opzioni di spedizione anche in base all'indirizzo di spedizione del cliente. Questa opzione è utile quando un commerciante vuole offrire diversi set di opzioni di spedizione per i clienti nazionali e internazionali.

Evento di convalida del commerciante

Per una maggiore sicurezza, un'app di pagamento può eseguire una convalida del commerciante prima di procedere con il flusso di pagamento. La progettazione del meccanismo di convalida è a carico dell'app di pagamento, ma l'evento di convalida del commerciante serve a informare il commerciante dell'URL che può utilizzare per convalidarsi.

request.addEventListener('merchantvalidation', e => {
  e.updateWith({
    // Use `e.validateURL` to validate
  });
});

Passaggio 6: il commerciante convalida il pagamento e completa la transazione

Quando il cliente autorizza correttamente il pagamento, il metodo show() restituisce una promessa che si risolve in un PaymentResponse. L'oggetto PaymentResponse include le seguenti informazioni:

• Dettagli del risultato del pagamento
• Indirizzo di spedizione
• Opzione di spedizione
• Informazioni di contatto

A questo punto, l'interfaccia utente del browser potrebbe ancora mostrare un indicatore di caricamento, il che significa che la transazione non è ancora stata completata.

Se l'app di pagamento viene interrotta a causa di un errore o di un mancato pagamento, la promessa restituita da show() viene rifiutata e il browser termina la transazione di pagamento.

Elaborazione e convalida del pagamento

details in PaymentResponse è l'oggetto delle credenziali di pagamento restituito dall'app di pagamento. Il commerciante può utilizzare la credenziale per elaborare o convalidare il pagamento. Il funzionamento di questa procedura fondamentale dipende dall'amministratore dei pagamenti.

Completare o riprovare a effettuare la transazione

Dopo che il commerciante ha stabilito se la transazione è andata a buon fine o meno, può:

• Chiama il metodo .complete() per completare la transazione e chiudere l'indicatore di caricamento.
• Chiedi al cliente di riprovare chiamando il metodo retry().

async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}

async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong…
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

Passaggi successivi

• Scopri come dichiarare un identificatore del metodo di pagamento in dettaglio in Configurare un metodo di pagamento.
• Scopri come creare un'app di pagamento specifica per la piattaforma nella Guida per gli sviluppatori di app di pagamento Android.
• Per scoprire come creare un'app di pagamento basata sul web, consulta la Guida per gli sviluppatori di app di pagamento basate sul web.