Cómo adaptar tu app de pagos basada en la Web a Pagos web 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 un pago del proceso de trabajo, el service worker como el centro de comunicación entre el comercio y la app de pagos. Esta publicación se explica cómo una app de pagos puede pasar información sobre la forma de pago dirección de envío o información de contacto al comerciante mediante un service worker.
![Cómo administrar la información de pago opcional con un service worker](https://web.developers.google.cn/static/articles/handling-optional-payment-information/image/handling-optional-payment-9e082afff222b.png?authuser=5&hl=es)
Cómo 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 | Emisor de tarjeta de crédito 1 | ****1234 |
Emisor de tarjeta de crédito 1 | ****4242 |
|
Banco X | ******123 |
|
B | Entidad emisora de la 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 créditos
y una cuenta bancaria registrada. En este caso, la app controla tres
instrumentos de pago (****1234
, ****4242
, ******123
) y dos formas de pago
(Emisor de la Tarjeta de Crédito 1 y Banco X). En una transacción de pago, el importe del
La app puede permitir que el cliente elija uno de los instrumentos de pago y lo use para pagar.
para el comercio.
![IU del selector de formas de pago](https://web.developers.google.cn/static/articles/handling-optional-payment-information/image/payment-method-picker-ui-83cf9bfe052f4.png?authuser=5&hl=es)
La app de pagos puede informarle al comercio qué forma de pago debe usar el cliente. seleccionados antes de enviar la respuesta completa del pago. Esto es útil cuando el elemento El comercio quiere publicar una campaña de descuentos para una marca específica de formas de pago, por ejemplo.
Con la API de Payment Handler, la app de pagos puede enviar un "cambio de la forma de pago".
para el comercio mediante un service worker que notifique a la nueva forma de pago.
identificador. El service worker debe invocar
PaymentRequestEvent.changePaymentMethod()
por la nueva forma de pago
información.
![Cómo informar al comercio sobre un cambio en la forma de pago](https://web.developers.google.cn/static/articles/handling-optional-payment-information/image/inform-merchant-a-payme-9ae9bd3b7b774.png?authuser=5&hl=es)
Las apps de pagos pueden pasar un objeto methodDetails
como el segundo argumento opcional
para PaymentRequestEvent.changePaymentMethod()
. Este objeto puede contener
detalles de la forma de pago arbitraria necesaria para que el comerciante procese el cambio
para cada evento.
[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
del pago
Request API, pueden actualizar los detalles del pago y responder con un
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
PaymentRequestEvent.changePaymentMethod()
que se devuelve resolverá con un
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 el artículo Refleja la actualización detalles del pago.
Cómo informar al comerciante sobre un cambio en la dirección de envío
Las apps de pago 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 porque pueden delegar la recopilación de direcciones a y apps de pago. Además, como los datos de la dirección se proporcionarán en la página formato de datos, el comercio puede esperar recibir las direcciones de envío en una estructura coherente.
Además, los clientes pueden registrar la información de su dirección con su con la app de pagos preferida y reutilizarla para distintos comercios.
![IU del selector de direcciones de envío](https://web.developers.google.cn/static/articles/handling-optional-payment-information/image/shipping-address-picker-u-2f452a9725ce3.png?authuser=5&hl=es)
Las apps de pago pueden proporcionar una IU para editar una dirección de envío o seleccionarla información de la dirección registrada previamente del cliente en una transacción de pago. Cuando se determina una dirección de envío temporalmente, la aplicación de pago puede permitir conocer al comerciante la información de la dirección oculta. Esto brinda a los comercios varios beneficios:
- Un comercio puede determinar si el cliente cumple con la restricción regional para enviar el artículo (por ejemplo, solo para uso nacional).
- Un comercio puede cambiar la lista de opciones de envío según la región del dirección de envío (por ejemplo, internacional normal o exprés).
- Un comercio puede aplicar el nuevo costo de envío según la dirección y actualizar el precio total.
Con la API de Payment Handler, la app de pagos puede enviar una "dirección de envío"
cambio" evento al comerciante desde el service worker para notificar el nuevo envío
web. El service worker debe invocar
PaymentRequestEvent.changeShippingAddress()
con la nueva dirección
.
![Cómo informar al comerciante sobre un cambio en la dirección de envío](https://web.developers.google.cn/static/articles/handling-optional-payment-information/image/inform-merchant-a-shipp-414e5048c9eb4.png?authuser=5&hl=es)
[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
del pago
Solicita la API para que pueda responder con la PaymentDetailsUpdate
actualizada.
[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 devuelve resolverá con un
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 el artículo Refleja la actualización detalles del pago.
Cómo informar al comercio sobre un cambio en las opciones de envío
Las opciones de envío son métodos de entrega que los comercios usan 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 premium internacional
Cada uno tiene su propio costo. Por lo general, las opciones o los métodos más rápidos son más costosos.
Los comercios que usan la API Payment Request pueden delegar esta selección a un . La app de pago puede usar la información para crear una IU y dejar que la el cliente elige una opción de envío.
![IU del selector de opciones de envío](https://web.developers.google.cn/static/articles/handling-optional-payment-information/image/shipping-option-picker-ui-a337c6acfbf94.png?authuser=5&hl=es)
La lista de opciones de envío especificada en la API de Payment Request del comercio es
se propaga al service worker de la app de pago como una propiedad
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 tiene el cliente. que elegiste. Esto es importante tanto para el comercio como para el cliente cambiar la opción de envío también cambia el precio total. El comercio necesita para que se te informe el precio más reciente para la verificación del pago más tarde y el el cliente también debe estar al tanto del cambio.
Con la API de Payment Handler, la app de pagos puede enviar una “opción de envío”.
cambio" al comercio desde el service worker. El service worker debería
invocar
PaymentRequestEvent.changeShippingOption()
con el nuevo ID de la opción de envío.
![Cómo informar al comercio sobre un cambio en las opciones de envío](https://web.developers.google.cn/static/articles/handling-optional-payment-information/image/inform-merchant-a-shipp-8f67c21bfb63e.png?authuser=5&hl=es)
[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
del pago
API de solicitud. El comercio debe usar la información para actualizar el precio total.
y, luego, respondes con la versión
PaymentDetailsUpdate
[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
PaymentRequestEvent.changeShippingOption()
que se devuelve resolverá con un
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 el artículo Refleja la actualización detalles del pago.
Refleja los detalles del pago actualizados
Una vez que el comercio termina de actualizar los detalles del pago, se devuelven las promesas
desde .changePaymentMethod()
, .changeShippingAddress()
y
.changeShippingOption()
se resolverá con un
PaymentRequestDetailsUpdate
. El controlador de pago puede usar el resultado para reflejar el precio total actualizado
y opciones de envío a la IU.
Los comercios pueden mostrar errores por varios motivos:
- No se acepta la 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. alguna otra razón.
Usa las siguientes propiedades para reflejar el estado de error:
error
: Es una cadena de error legible. Esta es la mejor cadena para mostrar a los clientes.shippingAddressErrors
AddressErrors
que contiene una cadena de error en detalle por propiedad de dirección. Este es útil si deseas abrir un formulario que permite al cliente editar su dirección y debes apuntarlas directamente a los campos no válidos.paymentMethodErrors
: Es un objeto de error específico de la forma de pago. Puedes hacer lo siguiente: que los comerciantes proporcionen un error estructurado, pero los autores de recomendamos que sea una cadena simple.
Código de muestra
La mayoría de los códigos de muestra que viste en este documento eran extractos de los siguientes documentos App de ejemplo que funciona:
https://paymenthandler-demo.glitch.me
service worker [controlador de pagos]
Frontend de [controlador de pagos]
Para probarlo, haz lo siguiente:
- Ve a https://paymentrequest-demo.glitch.me/.
- Ve a la parte inferior de la página.
- Presiona Agregar un botón de pago.
- Ingresa
https://paymenthandler-demo.glitch.me
en el campo Payment Method Identifier (Identificador de la forma de pago). - Presiona el botón Pagar junto al campo.