Scopri come i commercianti integrano le app di pagamento e come funzionano le transazioni di pagamento con l'API Payment Request.
Le API Web Payments sono funzionalità di pagamento dedicate integrate per la prima volta nel browser. Con i pagamenti web, l'integrazione dei commercianti con le app di pagamento diventa più semplice, mentre l'esperienza del cliente viene semplificata e resa più 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:
- 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 di pagamento.
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.
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 costruendo 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 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
opickup
) facoltativo inPaymentRequest
. 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'
});
Alcuni gestori dei pagamenti potrebbero richiedere al commerciante di fornire l'ID transazione che ha emesso in anticipo nell'ambito delle informazioni sulla transazione. Un'integrazione tipica include la comunicazione tra il server del commerciante e quello dell'amministratore dei pagamenti per prenotare il prezzo totale. In questo modo, i clienti malintenzionati non possono manipolare il prezzo e truffare il commerciante con una convalida al termine della transazione.
Il commerciante può passare un ID transazione nell'ambito della proprietà data
dell'oggetto PaymentMethodData
.
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 scoprire come funziona nel dettaglio la procedura 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
non utilizzabile è un'esperienza utente negativa. 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ò verificare se un cliente ha a disposizione 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" indica che è stata rilevata un'app di pagamento che supporta il metodo di pagamento e che l'app di pagamento specifica per la piattaforma è installata oppure che l'app di pagamento 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 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 alla risoluzione della promessa e all'inizio della transazione.
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 avvia immediatamente l'interfaccia utente di pagamento.
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.
Quando l'app di pagamento viene lanciata, riceve le informazioni sulla transazione comunicate all'oggetto PaymentRequest
nel passaggio 1, tra cui:
- 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 gestire 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 è comodo 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 - Senza costi
- 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ò 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 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 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, 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 della credenziale 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 per Android.
- Scopri come creare un'app di pagamento basata sul web nella guida per gli sviluppatori di app di pagamento basate sul web.