Saltar al contenido principal
Disponible desde Yuno Android SDK 2.24.0 y Yuno Web SDK 1.10.8. El desglose del pedido, las actualizaciones de la dirección de envío y el selector de método de envío convierten la hoja de Google Pay en un express checkout:
  • 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.
Cada capacidad es opcional. Si no las usas, tu integración de Google Pay funciona exactamente igual que antes.

Requisitos

En Android, actualizar a 2.24.0 es un cambio incompatible.
  • Establece minSdkVersion en 23 o superior. Con 21 o 22 la compilación falla en el paso de combinación del manifest.
  • Si tu app fija com.google.android.gms:play-services-wallet en una versión anterior a 20.0.0, quita esa fijación o usa 20.0.0 o superior.
  • Si llamas a startCheckout, startPayment, startPaymentLite, startPaymentSeamlessLite o continuePayment pasando todos los argumentos por posición, actualiza la llamada: se agregó un nuevo parámetro opcional antes del último callback. Las llamadas que usan argumentos con nombre o una lambda final no necesitan cambios.
Consulta el changelog del SDK de Android para más detalles.
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

  1. Tu backend agrega summary_items y/o shipping_methods cuando crea la sesión de checkout.
  2. Tu app registra onShippingAddressChanged cuando inicia el flujo de pago.
  3. 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.
  4. Después de que el cliente autoriza, el token de un solo uso incluye un objeto shipping con el método seleccionado y la dirección completa.
Dos reglas aplican en todos los casos:
  • Cada lista summary_items debe terminar con el total general. Su amount es el total que se muestra en la hoja, y su label se 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)

Agrega summary_items cuando crees la sesión de checkout:
Ahora la hoja muestra un desglose expandible con el total etiquetado como “ACME Inc.”. No se necesita código en la app.
  • Los ids subtotal, shipping, tax y discount usan 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

Agrega shipping_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:
El selector necesita el handler del Paso 3. Sin él, la hoja ignora los métodos y funciona como antes.
  • 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”. detail se muestra como la descripción.
  • Cambiar de método nunca llama a tu app ni a tu backend. El total proviene de los summary_items de ese método.
  • Los summary_items de 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

Registra onShippingAddressChanged 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á.
El mismo parámetro opcional existe en 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 con null para dejar la hoja como está. En Android llama a complete(...); en Web devuelve el valor desde el handler.

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.
Un error en la hoja no bloquea el pago. El cliente aún puede pagar, y el token lleva la dirección que rechazaste. Valida siempre la dirección en tu servidor cuando crees el pago. Si una venta no debe realizarse, no devuelvas ningún método de envío disponible para esa dirección.

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 en callbackOTT (Android) o createPayment (Web) incluye un objeto shipping con la dirección completa y el método seleccionado:
  • method es 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_items no se devuelven.
  • Si no registras un handler, el token no incluye shipping.
Usa este objeto en tu servidor para cobrar el monto final, validar la dirección y enviar el pedido.

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.

Solución de problemas