Come adattare la tua app di pagamento basata sul web a Pagamenti web e offrire una migliore esperienza utente ai clienti.
Quando un'app di pagamento basata sul web riceve una richiesta di pagamento e avvia una transazione di pagamento, il service worker fungerà da hub per la comunicazione tra il commerciante e l'app di pagamento. Questo post spiega come un'app di pagamento può trasmettere al commerciante informazioni sul metodo di pagamento, sull'indirizzo di spedizione o sui dati di contatto utilizzando un service worker.
Informare il commerciante di una 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 della carta di credito 1 | ****1234 |
Emittente della carta di credito 1 | ****4242 |
|
Banca X | ******123 |
|
B | Emittente della carta di credito 2 | ****5678 |
Banca X | ******456 |
Ad esempio, nella tabella precedente, il portafoglio 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 di carte di credito 1 e banca X). In una transazione di pagamento, l'app di pagamento può consentire al cliente di scegliere uno degli strumenti di pagamento e utilizzarlo per pagare per il commerciante.
L'app di pagamento può comunicare al commerciante il metodo di pagamento scelto dal cliente prima di inviare la risposta completa al pagamento. Ad esempio, è utile quando il commerciante vuole pubblicare una campagna di sconto per un brand di metodi di pagamento specifico.
Con l'API Payment Handler, l'app di pagamento può inviare un evento "modifica del metodo di pagamento" al commerciante tramite un service worker per notificare l'identificatore del nuovo metodo di pagamento. Il service worker deve invocare
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 dettagli arbitrari del metodo di pagamento necessari per consentire al commerciante di elaborare l'evento di modifica.
[payment handler] 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 PaymentRequest, può aggiornare i dettagli di pagamento e rispondere con un oggetto PaymentDetailsUpdate
.
[merchant]
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()
è stata restituita verrà risolta con un
PaymentRequestDetailsUpdate
oggetto.
[payment handler] 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 Aggiornare i dettagli di pagamento.
Informare il commerciante di una modifica dell'indirizzo di spedizione
Le app di pagamento possono fornire al commerciante l'indirizzo di spedizione di un cliente nell'ambito di una transazione di pagamento.
Questo è utile per i commercianti perché possono delegare la raccolta degli indirizzi alle app di pagamento. Inoltre, poiché i dati dell'indirizzo verranno forniti nel formato di dati standard, il commerciante può aspettarsi di ricevere indirizzi di spedizione in una struttura coerente.
Inoltre, i clienti possono registrare i dati del proprio indirizzo con la loro app di pagamento preferita e riutilizzarli per diversi commercianti.
Le app di pagamento possono fornire un'interfaccia utente per modificare un indirizzo di spedizione o selezionare i dati dell'indirizzo preregistrato del cliente in una transazione di pagamento. Quando un indirizzo di spedizione viene determinato temporaneamente, l'app di pagamento può comunicare al commerciante le informazioni sull'indirizzo oscurate. Questo offre ai commercianti diversi vantaggi:
- Un commerciante può stabilire se il cliente soddisfa la limitazione regionale per la spedizione dell'articolo (ad es. solo per uso nazionale).
- Un commerciante può modificare l'elenco delle opzioni di spedizione in base alla regione dell'indirizzo di spedizione (ad es. internazionale standard o espresso).
- 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 un evento "modifica indirizzo spedizione" al commerciante dal service worker per notificare il nuovo indirizzo spedizione. Il service worker deve invocare
PaymentRequestEvent.changeShippingAddress()
con l'oggetto nuovo indirizzo.
[payment handler] 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 PaymentRequest, in modo da poter rispondere con l'elemento PaymentDetailsUpdate
aggiornato.
[merchant]
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()
ritornata verrà risolta con un
PaymentRequestDetailsUpdate
oggetto.
[payment handler] 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 Aggiornare i dettagli di pagamento.
Comunicare al commerciante una modifica dell'opzione di spedizione
Le opzioni di spedizione sono i metodi di consegna utilizzati dai commercianti per spedire gli articoli acquistati a un cliente. Le opzioni di spedizione più comuni sono:
- Spedizione gratuita
- Spedizione espressa
- Spedizione internazionale
- Spedizione internazionale premium
Ognuno ha il proprio costo. In genere, i metodi/le 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 specificate nell'API Payment Request del commerciante viene propagato al service worker dell'app di pagamento come proprietà di PaymentRequestEvent
.
[merchant]
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 selezionata dal cliente. Questo è importante sia per il commerciante sia per il cliente perché la modifica dell'opzione di spedizione comporta anche la modifica del prezzo totale. Il commerciante deve essere informato del prezzo più recente 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 un evento "modifica dell'opzione di spedizione" al commerciante dal service worker. Il worker del servizio deve invocare PaymentRequestEvent.changeShippingOption()
con il nuovo ID opzione di spedizione.
[payment handler] 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 PaymentRequest. Il commerciante deve utilizzare le informazioni per aggiornare il prezzo totale
e poi rispondere con il messaggio aggiornato
PaymentDetailsUpdate
.
[merchant]
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()
è stata restituita verrà risolta con un
PaymentRequestDetailsUpdate
oggetto.
[payment handler] 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 Aggiornare i dettagli di pagamento.
Riflettono i dati di pagamento aggiornati
Una volta che il commerciante ha completato l'aggiornamento dei 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 aggiornato
e le opzioni di spedizione nell'interfaccia utente.
I commercianti potrebbero restituire errori per diversi motivi:
- Il metodo di pagamento non è accettabile.
- L'indirizzo di spedizione si trova al di fuori delle regioni supportate.
- L'indirizzo di spedizione contiene informazioni non valide.
- L'opzione di spedizione non è selezionabile per l'indirizzo di spedizione fornito o per qualche altro motivo.
Utilizza le seguenti proprietà per riflettere lo stato dell'errore:
error
: stringa di errore leggibile. Questa è la stringa migliore da mostrare ai clienti.shippingAddressErrors
:AddressErrors
oggetto che contiene la stringa di errore dettagliata per proprietà indirizzo. Questa opzione è utile se vuoi aprire un modulo che consenta al cliente di modificare il proprio indirizzo e devi indirizzarlo direttamente ai campi non validi.paymentMethodErrors
: oggetto dell'errore specifico per il 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 di esempio
La maggior parte dei codici di esempio che hai visto in questo documento erano estratti dalla seguente app di esempio funzionante:
https://paymenthandler-demo.glitch.me
[payment handler] service worker
[payment handler] frontend
Per provarlo:
- Vai alla pagina https://paymentrequest-demo.glitch.me/.
- Vai alla parte inferiore della pagina.
- Premi il pulsante Aggiungi un pagamento.
- Inserisci
https://paymenthandler-demo.glitch.me
nel campo Identificatore metodo di pagamento. - Premi il pulsante Paga accanto al campo.