- Desglose del pedido: muestra el subtotal, el envío, los impuestos y los descuentos en lugar de un solo total.
- Actualizaciones de la dirección de envío: recalcula el pedido cuando el cliente elige o cambia su dirección de envío, sin salir de la hoja.
- Selector de método de envío: permite que el cliente elija Standard, Express o Same-day en la hoja, con actualizaciones de precio instantáneas.
Requisitos
En Web no hay cambios incompatibles ni cambios en la página: el SDK carga y configura Google Pay por ti. Si cargas una versión fija del SDK (por ejemplo, con un hash de integridad), asegúrate de que sea 1.10.8 o posterior.
Cómo funciona
- Tu backend agrega
summary_itemsy/oshipping_methodscuando crea la sesión de checkout. - Tu app registra
onShippingAddressChangedcuando inicia el flujo de pago. - En la hoja de Google Pay, cambiar el método de envío actualiza el precio al instante sin llamar a tu app. Elegir o cambiar la dirección de envío llama a tu handler, para que puedas devolver nuevos totales, nuevos métodos o un error.
- Después de que el cliente autoriza, el token de un solo uso incluye un objeto
shippingcon el método seleccionado y la dirección completa.
- Cada lista
summary_itemsdebe terminar con el total general. Suamountes el total que se muestra en la hoja, y sulabelse muestra junto a él (recomendamos el nombre de tu tienda). - Todos los montos deben usar la moneda de la sesión. Si la moneda es distinta, el SDK ignora ese desglose o esa respuesta.
Paso 1: muestra el desglose del pedido (solo backend)
Agregasummary_items cuando crees la sesión de checkout:
- Los ids
subtotal,shipping,taxydiscountusan los tipos de línea nativos de Google. Cualquier otro id se muestra como una línea normal. El cliente solo ve tus etiquetas. - La última entrada debe ser el total general y debe coincidir con el monto de la sesión (tolerancia de 0.001 en Android, 0.01 en Web). Si no coincide, la hoja muestra solo el total.
- Los descuentos pueden ser negativos, por ejemplo
-5.00. - Envía al menos dos entradas: una línea más el total general. Si la lista no es válida (menos de dos entradas, falta una etiqueta o un monto, monedas mezcladas, sin total), la hoja muestra solo el total. Nada se rompe y el cliente no ve ningún error.
- Sin desglose, el Web SDK etiqueta el monto como “Total” en el idioma del checkout (SDK 1.11.17 o posterior).
- Cuando también envías
shipping_methods(Paso 2) y registras el handler, la hoja muestra el desglose del primer método y esta lista se ignora.
Paso 2: ofrece métodos de envío en la hoja
Agregashipping_methods a la sesión de checkout. Cada método tiene sus propios summary_items, de modo que la hoja pueda actualizar el precio apenas el cliente cambie de método:
- Cada método necesita un id único. Si dos métodos comparten un id, el selector no se muestra.
- El primer método viene preseleccionado.
- El precio se muestra en el nombre de la opción, por ejemplo “$5.00: Standard shipping”.
detailse muestra como la descripción. - Cambiar de método nunca llama a tu app ni a tu backend. El total proviene de los
summary_itemsde ese método. - Los
summary_itemsde cada método deben terminar con el total de ese método, que puede ser distinto del monto de la sesión. Envía al menos una línea más el total. Un método que solo tiene el total no muestra desglose y usa la etiqueta de total predeterminada de Google. - Si algún método no es válido, el selector no se muestra.
delivery_estimate({ "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }) se acepta, pero Google Pay no lo muestra ni en Android ni en Web.
Paso 3: reacciona a los cambios de la dirección de envío
RegistraonShippingAddressChanged cuando inicies el flujo. Tu handler recibe la dirección censurada y responde con nuevos totales, nuevos métodos, un error o nada para dejar la hoja como está.
- Android
- Web
startPayment, startPaymentLite, startPaymentSeamlessLite y continuePayment. Regístralo cada vez que inicies un flujo.Lo que recibes: ShippingInfo
Antes de la autorización, Google comparte solo una parte de la dirección, que es suficiente para cotizar el envío y los impuestos:
Cualquier campo puede faltar:
null en Android, ausente en Web. La dirección completa llega en el token de un solo uso (Paso 4).
Lo que devuelves: ShippingUpdate
Responde con cualquier combinación de estos elementos, o connull para dejar la hoja como está. En Android llama a complete(...); en Web devuelve el valor desde el handler.
- Android
- Web
Reglas
Para cambiar los precios mientras se muestra el selector, devuelve la lista completa de
shippingMethods, cada método con sus propios summaryItems. Si devuelves solo summaryItems, el total cambia, pero la próxima vez que el cliente cambie de método la hoja vuelve al desglose original de ese método.
Paso 4: lee el resultado en el token de un solo uso
Después de que el cliente autoriza, el token de un solo uso que recibes encallbackOTT (Android) o createPayment (Web) incluye un objeto shipping con la dirección completa y el método seleccionado:
methodes el seleccionado en la hoja, o el primero si el cliente no lo cambió. Su etiqueta es la que enviaste, sin el precio.- Los campos vacíos de la dirección llegan como cadenas vacías en Android y se omiten en Web.
- Los
summary_itemsno se devuelven. - Si no registras un handler, el token no incluye
shipping.
Qué ocurre en cada caso
Buenas prácticas
- Las direcciones pertenecen a la cuenta de Google del cliente. En el entorno TEST de Google Pay solo verás las direcciones de prueba de Google; no puedes agregar las tuyas.
- La hoja solicita una dirección de envío apenas se registra el handler. Sin un handler, solo la solicita cuando la dirección de envío está habilitada como campo obligatorio en el Checkout Builder.
- El método seleccionado sigue seleccionado cuando el cliente cambia la dirección, a menos que devuelvas nuevos métodos.
- Privacidad: el SDK nunca registra direcciones, correos electrónicos ni datos de pago.
- Google Pay Pix (Brasil) no se ve afectado.