Come adattare l'app per pagamenti basata sul web ai pagamenti web e offrire una migliore esperienza utente ai clienti.
Quando un'app per pagamenti basata sul web riceve una richiesta di pagamento e avvia una transazione di pagamento, il service worker agirà da hub per la comunicazione tra il commerciante e l'app di pagamento. Questo post spiega in che modo un'app di pagamento può trasmettere informazioni sul metodo di pagamento, sull'indirizzo di spedizione o sui dati di contatto al commerciante utilizzando un service worker.
Informare il commerciante della modifica del metodo di pagamento
Le app di pagamento possono supportare più strumenti di pagamento con metodi di pagamento diversi.
Cliente | Metodo di pagamento | Strumento di pagamento |
---|---|---|
A | Emittente carta di credito 1 | ****1234 |
Emittente carta di credito 1 | ****4242 |
|
Banca X | ******123 |
|
B | Emittente carta di credito 2 | ****5678 |
Banca X | ******456 |
Ad esempio, nella tabella sopra, il portafoglio basato sul web del Cliente A ha due carte di credito e un conto bancario registrati. In questo caso, l'app gestisce tre
strumenti di pagamento (****1234
, ****4242
, ******123
) e due metodi di
pagamento (emittente della carta di credito 1 e banca X). Nel caso di una transazione di pagamento, l'app di pagamento consente al cliente di scegliere uno degli strumenti di pagamento e di utilizzarlo per pagare il commerciante.
L'app di pagamento può indicare al commerciante il metodo di pagamento scelto dal cliente prima di inviare la risposta di pagamento completa. Questa opzione è utile, ad esempio, quando il commerciante vuole pubblicare una campagna di sconti per un brand specifico del metodo di pagamento.
Con l'API Payment Handler, l'app di pagamento può inviare un evento di "modifica del metodo di pagamento" al commerciante tramite un service worker per notificare il nuovo identificatore del metodo di pagamento. Il service worker deve richiamare
PaymentRequestEvent.changePaymentMethod()
con le informazioni sul nuovo metodo di
pagamento.
Le app di pagamento possono passare un oggetto methodDetails
come secondo argomento facoltativo per PaymentRequestEvent.changePaymentMethod()
. Questo oggetto può contenere i dettagli del metodo di pagamento arbitrario necessari al commerciante per elaborare l'evento di 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
dall'API Payment
Request, può aggiornare i dettagli di pagamento e rispondere con un oggetto
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()
restituisce si risolverà con un
oggetto 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 l'interfaccia utente sul frontend. Consulta la pagina Visualizzare i dettagli di pagamento aggiornati.
Informare il commerciante della modifica dell'indirizzo di spedizione
Le app di pagamento possono fornire l'indirizzo di spedizione di un cliente al commerciante nell'ambito di una transazione di pagamento.
Questa funzionalità è utile per i commercianti perché possono delegare la raccolta di indirizzi alle app di pagamento. Inoltre, poiché i dati degli indirizzi verranno forniti nel formato dei dati standard, il commerciante può aspettarsi di ricevere gli indirizzi di spedizione con una struttura coerente.
Inoltre, i clienti possono registrare i dati dell'indirizzo con l'app per i pagamenti preferita e riutilizzarli per diversi commercianti.
Le app di pagamento possono fornire una UI per modificare un indirizzo di spedizione o selezionare i dati dell'indirizzo preregistrato del cliente in una transazione di pagamento. Quando viene determinato temporaneamente un indirizzo di spedizione, l'app per i pagamenti può comunicare al commerciante le informazioni sull'indirizzo oscurato. Ciò offre ai commercianti più vantaggi:
- Un commerciante può stabilire se il cliente soddisfa la restrizione regionale per spedire l'articolo (ad esempio, solo per il mercato nazionale).
- Un commerciante può modificare l'elenco delle opzioni di spedizione in base alla regione dell'indirizzo di spedizione (ad esempio, normale internazionale o express).
- Un commerciante può applicare il nuovo costo di spedizione in base all'indirizzo e aggiornare il prezzo totale.
Con l'API Payment Handler, l'app di pagamento può inviare al commerciante un evento di "modifica dell'indirizzo di spedizione" dal service worker per notificare il nuovo indirizzo di spedizione. Il service worker deve richiamare
PaymentRequestEvent.changeShippingAddress()
con l'oggetto
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'API Payment
Request in modo da poter rispondere con l'aggiornamento 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()
restituita si risolverà con un
oggetto
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 l'interfaccia utente sul frontend. Consulta la pagina Visualizzare i dettagli di pagamento aggiornati.
Informare il commerciante della 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 tipiche includono:
- Spedizione gratuita
- Spedizione espressa
- Spedizione internazionale
- Spedizione internazionale premium
Ognuna ha il suo costo. Di solito i metodi/opzioni più veloci sono più costosi.
I commercianti che utilizzano l'API Payment Request possono delegare questa selezione a un'app di pagamento. L'app di pagamento può utilizzare le informazioni per creare un'interfaccia utente e consentire al cliente di scegliere un'opzione di spedizione.
L'elenco delle opzioni di spedizione specificato nell'API Payment Request del commerciante viene
propagato al service worker dell'app di pagamento come proprietà di
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 l'opzione di spedizione scelta dal cliente. Questo è importante sia per il commerciante che per il cliente, perché la modifica dell'opzione di spedizione cambia anche il prezzo totale. Il commerciante deve essere informato dell'ultimo prezzo per la verifica del pagamento in un secondo momento e anche il cliente deve essere a conoscenza della modifica.
Con l'API Payment Handler, l'app di pagamento può inviare al commerciante un evento di "modifica dell'opzione di spedizione" 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'API Payment
Request. Il commerciante deve utilizzare le informazioni per aggiornare il prezzo totale
e poi rispondere con il
PaymentDetailsUpdate
aggiornato.
[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()
restituisce si risolverà con un
oggetto 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 l'interfaccia utente sul frontend. Consulta la pagina Visualizzare i dettagli di pagamento aggiornati.
Mostra i dettagli di pagamento aggiornati
Una volta che il commerciante avrà aggiornato i dettagli di pagamento, le promesse restituite
da .changePaymentMethod()
, .changeShippingAddress()
e
.changeShippingOption()
verranno risolte con un oggetto
PaymentRequestDetailsUpdate
comune. Il gestore dei pagamenti può utilizzare il risultato per riflettere il prezzo totale e le opzioni di spedizione aggiornati nella UI.
I commercianti potrebbero 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.
- L'opzione di spedizione non è selezionabile per l'indirizzo di spedizione fornito o per altri motivi.
Utilizza le seguenti proprietà per riflettere lo stato di errore:
error
: stringa di errore leggibile. Questa è la stringa migliore da mostrare ai clienti.shippingAddressErrors
:AddressErrors
oggetto contenente una stringa di errore dettagliata per proprietà indirizzo. È utile se vuoi aprire un modulo che consenta al cliente di modificare l'indirizzo in modo da indirizzarlo direttamente ai campi non validi.paymentMethodErrors
: oggetto di errore specifico del metodo di pagamento. Puoi chiedere ai commercianti di fornire un errore strutturato, ma gli autori delle specifiche di Pagamenti web consigliano di mantenere una stringa semplice.
Codice campione
La maggior parte dei codici di esempio che hai visto in questo documento era estratti dalla seguente app di esempio funzionante:
https://paymenthandler-demo.glitch.me
Service worker [gestore dei pagamenti]
frontend [gestore dei pagamenti]
Per provarla:
- Vai alla pagina https://paymentrequest-demo.glitch.me/.
- Vai alla parte inferiore della pagina.
- Premi Aggiungi un pulsante di pagamento.
- Inserisci
https://paymenthandler-demo.glitch.me
nel campo Identificatore metodo di pagamento. - Premi il pulsante Paga accanto al campo.