Modern Web Guidance è ora stabile. Esegui l'upgrade degli agenti di programmazione con best practice per lo sviluppo web verificate da esperti. Leggi l'annuncio.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Ciclo di vita di una transazione di pagamento

Scopri come i commercianti integrano le app per pagamenti 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 Web Payments, l'integrazione dei commercianti con le app per pagamenti diventa più semplice, mentre la customer experience viene semplificata e resa più sicura.

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

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

La procedura prevede sei passaggi:

Il commerciante avvia una transazione di pagamento.
Il commerciante mostra un pulsante di pagamento.
Il cliente preme il pulsante di pagamento.
Il browser avvia l'app per pagamenti.
Se il cliente modifica i dettagli (ad esempio le opzioni di spedizione o l'indirizzo), il commerciante aggiorna i dettagli della transazione in modo che riflettano la modifica.
Dopo che il cliente ha confermato 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 informazioni importanti sulla transazione:

Metodi di pagamento accettabili e relativi dati per elaborare la transazione.
Dettagli, come il prezzo totale (obbligatorio) e le informazioni sugli articoli.
Opzioni con cui i commercianti possono richiedere informazioni sulla spedizione, come un indirizzo di spedizione e un'opzione di spedizione.
I commercianti possono anche richiedere l'indirizzo di fatturazione, il nome, l'indirizzo email e il numero di telefono di chi effettua il pagamento.
I commercianti possono anche includere il tipo di spedizione facoltativo (shipping, delivery o pickup) in PaymentRequest. L'app per pagamenti può utilizzare queste informazioni 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'
});

Includi un ID transazione

Alcuni gestori dei pagamenti potrebbero richiedere al commerciante di fornire l'ID transazione che hanno emesso in anticipo nell'ambito delle informazioni sulla transazione. Un'integrazione tipica include la comunicazione tra il server del commerciante e quello del gestore dei pagamenti per prenotare il prezzo totale. In questo modo, i clienti malintenzionati non possono manipolare il prezzo e ingannare il commerciante con una convalida alla fine della transazione.

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

Una volta fornite le informazioni sulla transazione, il browser esegue un processo di rilevamento delle app per pagamenti specificate in PaymentRequest in base agli identificatori del metodo di pagamento. In questo modo, il browser può determinare l'app per pagamenti da avviare non appena il commerciante è pronto a procedere con la transazione.

Per scoprire in dettaglio come funziona la procedura di rilevamento, consulta Configura 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 un cliente può effettivamente utilizzare. Mostrare un pulsante di pagamento inutilizzabile è 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ò verificare se un cliente ha l'app per pagamenti disponibile.

Il cliente ha l'app per pagamenti disponibile?

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

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 l'avvio della UI di pagamento.

Se il prezzo totale finale viene impostato in modo dinamico (ad esempio, recuperato da un server), il commerciante può posticipare il lancio della UI di pagamento fino a quando non viene comunicato il totale.

Rinvio del lancio della UI di pagamento

Dai un'occhiata a una demo su come posticipare la UI di pagamento fino alla determinazione del prezzo totale finale.

Per posticipare la UI di pagamento, il commerciante passa una promise al metodo show(). Il browser mostrerà un indicatore di caricamento finché la promise 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 promise come argomento per show(), il browser avvierà immediatamente la UI di pagamento.

Passaggio 4: il browser avvia l'app per pagamenti

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

La modalità di creazione dell'app per pagamenti dipende in gran parte dallo sviluppatore, ma gli eventi emessi da e verso il commerciante, nonché la struttura dei dati trasmessi insieme a questi eventi, sono standardizzati.

All'avvio, l'app per pagamenti riceve le informazioni sulla transazione passate all'oggetto PaymentRequest nel passaggio 1, che includono:

Dati del metodo di pagamento
Prezzo totale
Opzioni di pagamento

L'app per pagamenti utilizza i dati della transazione per etichettare la propria UI.

Passaggio 5: come 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 per pagamenti. Mentre il cliente apporta le modifiche, il commerciante riceve gli eventi di modifica e aggiorna i dettagli della transazione.

Esistono quattro tipi di eventi che un commerciante può ricevere:

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 per pagamenti 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ò informare il commerciante del 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

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

Se un cliente aggiorna il proprio indirizzo di spedizione in un'app per pagamenti dopo l'avvio della transazione, verrà inviato un evento 'shippingaddresschange' al commerciante. 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 per pagamenti.

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

Se il commerciante non può spedire all'indirizzo aggiornato, può fornire un messaggio di errore aggiungendo un parametro di errore ai dettagli della transazione restituiti all'app per pagamenti.

Evento di modifica dell'opzione di spedizione

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

Spedizione standard: senza costi
Spedizione rapida - 5 $

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

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

Il commerciante può anche modificare dinamicamente le opzioni di spedizione 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 per pagamenti può eseguire una convalida del commerciante prima di procedere al flusso di pagamento. Il design del meccanismo di convalida dipende dall'app per pagamenti, 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 il pagamento, il metodo show() restituisce una promise che si risolve in un 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, la UI del browser potrebbe ancora mostrare un indicatore di caricamento, il che significa che la transazione non è ancora completata.

Se l'app per pagamenti viene terminata a causa di un errore o di un errore di 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 per pagamenti. Il commerciante può utilizzare le credenziali per elaborare o convalidare il pagamento. Il modo in cui funziona questo processo critico dipende dal gestore dei pagamenti.

Completamento o nuovo tentativo della transazione

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

Chiama il metodo .complete() per completare la transazione e chiudere 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 un identificatore del metodo di pagamento in dettaglio nella sezione Configurazione di un metodo di pagamento.
Scopri come creare un'app per pagamenti specifica per la piattaforma nella guida per gli sviluppatori di app per pagamenti Android.
Scopri come creare un'app per pagamenti basata sul web nella guida per gli sviluppatori di app per pagamenti basate sul web.