Para permitir que los usuarios realicen la compra, debes implementar la integración de compra nativa. Esto implica crear una API de REST estándar que permita a Google administrar de forma programática el proceso de confirmación de compra con tus servidores. Este método proporciona la experiencia más fluida para los usuarios. Inicialmente, Google renderizará la interfaz de usuario para el comprador, y, en el futuro, planea admitir experiencias más basadas en agentes.
Proceso de confirmación de compra
La integración nativa requiere que compiles una API de RESTful a la que Google pueda llamar para crear y administrar sesiones de confirmación de compra.
El flujo general es el siguiente:
- Compila la sesión de confirmación de compra: El usuario y, de forma opcional, un agente están en un bucle agregando elementos a la sesión.
- Transferencia a una IU de Google: Una vez que el usuario decide consultar el agente (si está involucrado), este le pasa el control a una IU de Google (y le pasa los datos de la sesión de confirmación de compra).
- Confirmación de compra manual: Ahora el usuario solo interactúa con la IU de Google para completar los detalles sensibles de cumplimiento y pago, y enviar el pedido. El agente no participa en esta parte, lo que garantiza el determinismo.
- Finalización y devolución: La IU de Google muestra una página de "Agradecimiento" para confirmar el pedido. De manera opcional, se puede redireccionar al usuario de vuelta al agente, quien ya podría haber recibido una notificación sobre la compra completada.
Ciclo de vida del estado de la sesión de pago
A medida que el usuario avanza en el flujo de pago, debes actualizar la sesión de pago status para que refleje su estado actual. La sesión pasa por el siguiente ciclo de vida:
incomplete: Es el estado inicial cuando se crea una sesión. Esto indica que falta información obligatoria (como métodos de envío, impuestos o detalles del usuario) o que no se calculó.ready_for_payment: Es el estado que se usará después de que el usuario actualice su dirección de envío y tú calcules las opciones y los totales de envío, pero antes de que se finalice el instrumento de pago.ready_for_complete: Es el estado que se usará durante la hidratación completa del objeto de confirmación de compra, una vez que se selecciona el instrumento de pago y se validan todos los detalles del pedido.completed: Es el estado final que se devuelve después de que procesas correctamente el pago y realizas el pedido.canceled: Es el estado que se devuelve si se anula la sesión de confirmación de compra.error: Es el estado que se devuelve si un error de lógica empresarial irrecuperable impide la confirmación de compra. Este estado está disponible en la versión2026-04-08y posteriores de UCP.
Proceso de confirmación de compra de varios artículos:
Ahora Google admite varias líneas de pedido distintas en una sola sesión de confirmación de compra. El flujo general es el siguiente:
- El usuario inicia la confirmación de la compra desde una interfaz habilitada para la UCP (p.ej., haciendo clic en "Comprar ahora" en un producto).
- Se realiza la llamada a
POST /checkout-sessions, incluidos todos los elementos distintos del arrayline_items. El arrayline_itemscontendrá un objeto independiente para cada artículo único que se retire. - El usuario puede actualizar su instrumento de pago, los detalles de cumplimiento o aplicar descuentos con llamadas a
PUT /checkout-sessions/{id}. - Cuando el usuario hace clic en el botón "Pagar con GPay", se realiza la llamada a
POST /checkout-sessions/{id}/complete.
Autenticación
Para obtener detalles sobre cómo proteger los extremos de la API de Native Checkout, incluidos los métodos de autenticación admitidos, como las claves de API y OAuth 2.0, consulta la guía de Autenticación y seguridad.
Herramientas para desarrolladores
Para ayudarte con la implementación de la API de Native Checkout, puedes encontrar los siguientes recursos en el repositorio de GitHub del Universal Commerce Protocol:
- Repositorio de GitHub de UCP: Explora el repositorio principal para obtener documentación integral, especificaciones y recursos de la comunidad.
- SDKs: Usa los kits de desarrollo de software para acelerar tu integración. Hay SDKs específicos para cada idioma, incluidos los siguientes:
Pruebas de conformidad: Valida tus extremos de API en función de la especificación de la UCP con el conjunto de pruebas de conformidad.
Esto te ayuda a garantizar que tu implementación cumpla con los estándares y comportamientos requeridos.
Te recomendamos que uses estas herramientas para optimizar tu proceso de desarrollo y pruebas.
Objetivos de nivel de servicio
Los siguientes objetivos de nivel de servicio (SLO) se aplican a los extremos de la API de Native Checkout REST. Se espera que las empresas que se integran con Google cumplan con estos objetivos de rendimiento y disponibilidad de la API.
| Extremo | Disponibilidad | Latencia (percentil 50) | Latencia (percentil 95) |
|---|---|---|---|
POST /checkout-sessions (Crear) |
>= 95% | <= 1 segundo | <= 4 segundos |
PUT /checkout-sessions/{id} (Actualizar) |
>= 95% | <= 1 segundo | <= 5 segundos |
POST /checkout-sessions/{id}/complete (Completar) |
>= 95% | <= 6 segundos | <= 10 segundos |
La latencia del percentil 50 indica que se espera que, al menos, el 50% de las solicitudes se completen en este tiempo. La latencia del percentil 95 indica que se espera que, al menos, el 95% de las solicitudes se completen dentro de este período.
Próximos pasos
Consulta las cargas útiles de la API de Checkout y los detalles de implementación técnica para tu versión de UCP:
- Versión 2026-04-08 de la API de REST de la confirmación de compra nativa
- Versión 2026-01-23 de la API de REST de compra nativa
Si realizas la integración como proveedor de servicios externo, continúa con la configuración del servicio de confirmación de compra de UCP para alojar perfiles de comercios y configurar los acuerdos de relación de cuentas.