Cómo adaptar tu app de pagos basada en la Web a Web Payments y brindar una mejor experiencia del usuario a los clientes
Una vez que una app de pagos basada en la Web recibe una solicitud de pago e inicia una transacción de pago, el service worker actuará como el centro de comunicación entre el comercio y la app de pagos. En esta publicación, se explica cómo una app de pagos puede pasar información sobre la forma de pago, la dirección de envío o la información de contacto al comercio mediante un service worker.
Informar al comercio sobre un cambio en la forma de pago
Las apps de pago admiten varios instrumentos de pago con diferentes formas de pago.
| Cliente | Forma de pago | Instrumento de pago |
|---|---|---|
| A | Entidad emisora de la tarjeta de crédito 1 | ****1234 |
| Entidad emisora de la tarjeta de crédito 1 | ****4242 |
|
| Banco X | ******123 |
|
| B | Emisor de tarjeta de crédito 2 | ****5678 |
| Banco X | ******456 |
Por ejemplo, en la tabla anterior, la billetera basada en la Web del cliente A tiene dos tarjetas
de crédito y una cuenta bancaria registradas. En este caso, la app maneja tres instrumentos de pago (****1234, ****4242, ******123) y dos formas de pago (emisor de tarjeta de crédito 1 y banco X). En una transacción de pago, la app de pago puede permitir que el cliente elija uno de los instrumentos de pago y lo use para pagar por el comercio.
La app de pagos puede informarle al comercio qué forma de pago eligió el cliente antes de enviar la respuesta de pago completa. Esto es útil cuando el comercio quiera publicar una campaña de descuentos para una marca específica de forma de pago, por ejemplo.
Con la API de Payment Handler, la app de pagos puede enviar un evento de "cambio de forma de pago" al comercio a través de un service worker para notificar al nuevo identificador de la forma de pago. El service worker debe invocar a
PaymentRequestEvent.changePaymentMethod() con la información de la forma de pago nueva.
Las apps de pagos pueden pasar un objeto methodDetails como segundo argumento opcional para PaymentRequestEvent.changePaymentMethod(). Este objeto puede contener los detalles arbitrarios de las formas de pago necesarias para que el comercio procese el evento de cambio.
[controlador de pagos] 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);
…
Cuando el comercio recibe un evento paymentmethodchange de la API de Payment
Request, puede actualizar los detalles del pago y responder con un objeto
PaymentDetailsUpdate.
[comercio]
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);
});
Cuando el comercio responde, la promesa que mostró PaymentRequestEvent.changePaymentMethod() se resolverá con un objeto PaymentRequestDetailsUpdate.
[controlador de pagos] 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;
…
Usar el objeto para actualizar la IU en el frontend Consulta Refleja los detalles del pago actualizados.
Informar al comercio sobre un cambio en la dirección de envío
Las apps de pagos pueden proporcionar la dirección de envío de un cliente al comercio como parte de una transacción de pago.
Esto es útil para los comercios, ya que pueden delegar la recopilación de direcciones a las apps de pagos. Además, como los datos de dirección se proporcionarán en el formato de datos estándar, el comercio recibirá direcciones de envío en una estructura coherente.
Además, los clientes pueden registrar la información de su dirección con su app de pagos preferida y reutilizarla para diferentes comercios.
Las apps de pagos pueden proporcionar una IU para editar una dirección de envío o seleccionar la información de la dirección registrada previamente para el cliente en una transacción de pago. Cuando se determina una dirección de envío temporalmente, la app de pagos puede informar al comercio la información de la dirección oculta. Esto brinda a los comercios varios beneficios:
- El comercio puede determinar si el cliente cumple con la restricción regional para enviar el artículo (por ejemplo, solo a nivel nacional).
- Un comercio puede cambiar la lista de opciones de envío según la región de la dirección de envío (por ejemplo, internacional normal o expreso).
- El comercio puede aplicar el nuevo costo de envío en función de la dirección y actualizar el precio total.
Con la API de Payment Handler, la app de pagos puede enviar un evento de “cambio de dirección de envío” al comercio desde el service worker para notificar a la nueva dirección de envío. El service worker debe invocar a PaymentRequestEvent.changeShippingAddress() con el objeto de dirección nuevo.
[controlador de pagos] 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);
…
El comercio recibirá un evento shippingaddresschange de la API de Payment
Request para que pueda responder con el PaymentDetailsUpdate actualizado.
[comercio]
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);
});
Cuando el comercio responde, la promesa
PaymentRequestEvent.changeShippingAddress()
que se muestra se resolverá con un objeto
PaymentRequestDetailsUpdate.
[controlador de pagos] 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;
…
Usar el objeto para actualizar la IU en el frontend Consulta Refleja los detalles del pago actualizados.
Informar al comercio sobre un cambio en la opción de envío
Las opciones de envío son métodos de entrega que utilizan los comercios para enviar los artículos comprados a un cliente. Entre las opciones de envío típicas, se incluyen las siguientes:
- Envío gratis
- Envío exprés
- envíos internacionales
- Envío internacional premium
Cada uno tiene su propio costo. Por lo general, las opciones o métodos más rápidos son más costosos.
Los comercios que usan la API de Payment Request pueden delegar esta selección a una app de pagos. Esta última puede usar la información para crear una IU y permitir que el cliente elija una opción de envío.
La lista de opciones de envío especificadas en la API de Payment Request del comercio
se propaga al service worker de la app de pagos como una propiedad de
PaymentRequestEvent.
[comercio]
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 });
La app de pagos puede informarle al comercio qué opción de envío eligió el cliente. Esto es importante tanto para el comercio como para el cliente porque cambiar la opción de envío también cambia el precio total. Más adelante, se debe informar al comercio sobre el precio más reciente para la verificación del pago, y el cliente también debe estar al tanto del cambio.
Con la API de Payment Handler, la app de pagos puede enviar un evento de “cambio de opción de envío” desde el service worker al comercio. El service worker debe invocar a PaymentRequestEvent.changeShippingOption() con el nuevo ID de la opción de envío.
[controlador de pagos] 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);
…
El comercio recibirá un evento shippingoptionchange de la API de
Payment Request. El comercio debe usar la información para actualizar el precio total y, luego, responder con el PaymentDetailsUpdate actualizado.
[comercio]
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 });
});
Cuando el comercio responde, la promesa que mostró PaymentRequestEvent.changeShippingOption() se resolverá con un objeto PaymentRequestDetailsUpdate.
[controlador de pagos] 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;
…
Usar el objeto para actualizar la IU en el frontend Consulta Refleja los detalles del pago actualizados.
Reflejar los detalles del pago actualizados
Una vez que el comercio termina de actualizar los detalles del pago, las promesas que se muestran
de .changePaymentMethod(), .changeShippingAddress() y
.changeShippingOption() se resolverán con un objeto
PaymentRequestDetailsUpdate
común. El controlador de pagos puede usar el resultado para reflejar el precio total y las opciones de envío actualizadas en la IU.
Los comercios pueden mostrar errores por varios motivos:
- No se acepta esta forma de pago.
- La dirección de envío está fuera de sus regiones admitidas.
- La dirección de envío contiene información no válida.
- No se puede seleccionar la opción de envío para la dirección de envío proporcionada o por algún otro motivo.
Usa las siguientes propiedades para reflejar el estado de error:
error: Es una cadena de error legible por humanos. Esta es la mejor cadena para mostrar a los clientes.shippingAddressErrors: Es un objetoAddressErrorsque contiene una cadena de error detallada por propiedad de dirección. Esto es útil si deseas abrir un formulario que le permite al cliente editar su dirección y necesitas dirigirlo directamente a los campos no válidos.paymentMethodErrors: Es el objeto de error específico del método de pago. Puedes pedirles a los comercios que proporcionen un error estructurado, pero los autores de especificaciones de Pagos web recomiendan que uses una cadena simple.
Código de muestra
La mayoría de los códigos de muestra que viste en este documento eran extractos de la siguiente app de ejemplo funcional:
https://paymenthandler-demo.glitch.me
[controlador de pagos] service worker
Frontend de [controlador de pagos]
Para probarlo, sigue estos pasos:
- Ve a https://paymentrequest-demo.glitch.me/.
- Ve a la parte inferior de la página.
- Presiona el botón Agregar un pago.
- Ingresa
https://paymenthandler-demo.glitch.meen el campo Payment Method Identifier. - Presiona el botón Pagar junto al campo.