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 nel browser per la prima volta. Con i pagamenti web, l'integrazione dei commercianti con le app di pagamento diventa più semplice, mentre l'esperienza del cliente diventa più semplice e sicura.

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

Questo articolo illustra la procedura di transazione di pagamento sul sito web di un commerciante e ti aiuta a capire come funziona l'integrazione delle app per pagamenti.

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 eventuali dettagli (ad esempio le opzioni di spedizione o l'indirizzo), il commerciante aggiorna i dettagli della transazione per riflettere la 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 creando un oggetto PaymentRequest. Questo oggetto include importanti informazioni sulla transazione:

• Metodi di pagamento accettabili e relativi dati per l'elaborazione della transazione.
• Dettagli, ad esempio 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 del pagatore, l'indirizzo email e il numero di telefono.
• I commercianti possono anche includere un tipo di spedizione facoltativo (shipping, delivery o pickup) in PaymentRequest. L'app per pagamenti 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'
});

Inclusione di un ID transazione

Alcuni gestori dei pagamenti potrebbero richiedere al commerciante di fornire in anticipo l'ID transazione emesso nell'ambito delle informazioni sulla transazione. Un'integrazione tipica include le comunicazioni tra il server del commerciante e il server del gestore dei pagamenti per prenotare il prezzo totale. In questo modo è possibile impedire ai clienti malintenzionati di manipolare il prezzo e barare il commerciante con una convalida alla fine della transazione.

Il commerciante può passare un ID transazione come parte della proprietà data dell'oggetto PaymentMethodData.

Fornite le informazioni sulla transazione, il browser esegue una procedura di rilevamento delle app di pagamento specificate in PaymentRequest in base agli identificatori dei metodi di pagamento. In questo modo, il browser può stabilire l'avvio dell'app di pagamento non appena il commerciante è pronto a procedere con la transazione.

Per informazioni dettagliate su come funziona il 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 presentare i pulsanti di pagamento solo per quelli che i clienti possono effettivamente utilizzare. Mostrare un pulsante di pagamento inutilizzabile costituisce 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 di riserva o non mostrare affatto il pulsante.

Utilizzando un'istanza PaymentRequest, un commerciante può chiedere se un cliente ha disponibile l'app per pagamenti.

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 l'app di pagamento specifica per la piattaforma è installata o che l'app per pagamenti 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 per i pagamenti.

Se il prezzo totale finale viene impostato in modo dinamico (ad esempio, recuperato da un server), il commerciante può posticipare il lancio dell'interfaccia utente per i pagamenti finché non viene noto il totale.

Posticipare il lancio dell'interfaccia utente per i pagamenti

Guarda una demo su come rinviare l'interfaccia utente per i pagamenti fino a quando non viene determinato il prezzo totale finale.

Per rinviare l'interfaccia utente di pagamento, il commerciante trasmette una promessa al metodo show(). Il browser mostrerà un indicatore di caricamento fino a quando la promessa non viene risolta e la transazione non è 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 viene specificata alcuna promessa come argomento per show(), il browser avvia immediatamente l'interfaccia utente per i pagamenti.

Nota: se il gestore dei pagamenti è progettato per restituire un ID transazione al momento dell'impostazione del prezzo totale, l'ID può essere trasmesso come parte del risultato della promessa.

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 da e per il commerciante e la struttura dei dati trasmessi insieme a questi eventi sono standardizzati.

Quando viene avviata, l'app di pagamento riceve le informazioni sulla transazione trasmesse all'oggetto PaymentRequest nel Passaggio 1, che includono quanto segue:

• Dati dei metodi di pagamento
• Prezzo totale
• Opzioni di pagamento

L'app per pagamenti utilizza le informazioni sulla transazione per etichettare la propria UI.

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, come 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 uno sconto speciale a seconda della selezione del cliente. Per coprire questo caso d'uso, l'evento di modifica del metodo di pagamento può comunicare al commerciante il nuovo metodo di pagamento in modo che possa aggiornare il prezzo totale con lo sconto e restituirlo all'app per pagamenti.

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

Evento di modifica dell'indirizzo di spedizione

Facoltativamente, un'app di pagamento può fornire l'indirizzo di spedizione del cliente. Questa soluzione è comoda per i clienti perché non devono inserire manualmente i dati in un modulo e possono memorizzare l'indirizzo di spedizione nelle app di pagamento preferite, invece che su più siti web di commercianti diversi.

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

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

Se il commerciante non riesce a effettuare la spedizione all'indirizzo aggiornato, può mostrare un messaggio di errore aggiungendo un parametro di errore ai dettagli della transazione restituiti all'app per i pagamenti.

Nota: i commercianti non ricevono l'indirizzo di spedizione completo dei clienti finché non hanno autorizzato il pagamento.

Evento di modifica dell'opzione di spedizione

Un commerciante può offrire al cliente più opzioni di spedizione e può delegare tale 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ò selezionare. Ad esempio:

• Spedizione standard - Senza costi
• Spedizione espressa - 5 EUR

Quando un cliente aggiorna l'opzione di spedizione in un'app di pagamento, al commerciante verrà 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. È utile quando un commerciante vuole offrire gruppi diversi di opzioni di spedizione per clienti nazionali e internazionali.

Evento di convalida del commerciante

Per 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 dipende dall'app di pagamento, ma l'evento di convalida del commerciante serve a comunicare al commerciante l'URL da utilizzare per la convalida.

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

Nota: l'assistenza per l'evento di convalida del commerciante è limitata ad Apple Safari. I browser basati su Chromium non hanno implementato questo evento a partire da maggio 2020.

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

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

• Dettagli del risultato del pagamento
• Indirizzo di spedizione
• Opzione di spedizione
• Dati 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 per pagamenti viene interrotta a causa di un errore di pagamento o di un errore, la promessa restituita da show() viene rifiutata e il browser termina la transazione di pagamento.

Elaborazione e convalida del pagamento

Il 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 critica dipende dal gestore dei pagamenti.

Completare o riprovare la transazione

Dopo aver determinato se la transazione è stata eseguita o meno, il commerciante può:

• Richiama il metodo .complete() per completare la transazione e ignora l'indicatore di caricamento.
• Consenti 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 in dettaglio l'identificatore di un metodo di pagamento 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.
• Scopri come creare un'app di pagamento basata sul web nella Guida per gli sviluppatori di app di pagamento basate sul web.