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:
- Crea una 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 completar la compra, el agente (si está activo) transfiere el control a una IU de Google (y pasa los datos de la sesió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 "Gracias" para confirmar el pedido. De manera opcional, se puede redireccionar al usuario al agente, quien ya podría haber recibido una notificación sobre la compra completada.
En los siguientes pasos, se describen los extremos de API que deberás implementar y sus comportamientos.
1. Crea una sesión de confirmación de compra
Este extremo permite crear una sesión de confirmación de la compra que contiene los productos que un usuario desea comprar.
- Extremo:
POST /checkout-sessions - Activador: El usuario hace clic en "Comprar" en un producto.
Solicitud: Google envía las líneas de pedido y la moneda.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Respuesta: Devuelves la sesión inicializada con los totales, los impuestos (inicialmente estimados) y las capacidades de pago. Debes incluir vínculos a tus condiciones del servicio y política de privacidad, que se vincularán debajo del botón de pago.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [
{
"name": "dev.ucp.shopping.checkout",
"version": "2026-01-11"
},
{
"name": "dev.ucp.shopping.fulfillment",
"version": "2026-01-11"
}
]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "incomplete",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000
},
"quantity": 1,
"base_amount": 10000,
"subtotal": 10000,
"total": 10000
}
],
"totals": [
{ "type": "subtotal", "amount": 10000 }, // in cents
{ "type": "tax", "amount": 0 },
{ "type": "total", "amount": 10000 }
],
"payment": {
"handlers": [
{
"id": "gpay",
"name": "com.google.pay",
"config": {
"api_version": 2,
"api_version_minor": 0,
"merchant_info": {
"merchant_id": "12345678901234567890",
"merchant_name": "Example Merchant"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
"allowed_card_networks": ["VISA", "MASTERCARD"]
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"gateway_merchant_id": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
},
"links": [
{ "type": "privacy_policy", "url": "https://m.com/privacy" },
{ "type": "terms_of_service", "url": "https://m.com/terms" }
]
}
2. Obtén la sesión de confirmación de la compra
Este endpoint permite recuperar una sesión de confirmación de compra.
- Extremo:
GET /checkout-sessions/{id}
Solicitud: Google envía el ID de la sesión de confirmación de compra. Si usas IDs globales (p.ej., gid://merchant.example.com/Checkout/session_abc123), ten en cuenta que el ID en la ruta de acceso de la solicitud solo será el último componente de este ID (p.ej.,
session_abc123).
Respuesta: Devuelves el objeto de confirmación de compra completo.
3. Actualiza la sesión de confirmación de compra
Este extremo permite actualizar una sesión de compra. Cuando se actualiza la dirección de envío, se deben volver a calcular y mostrar los impuestos y las opciones de envío.
- Extremo:
PUT /checkout-sessions/{id} - Activador: El usuario selecciona o cambia su dirección de envío, actualiza su selección de envío o actualiza su información de pago.
Solicitud: Google envía el objeto de confirmación de compra completo con la información actualizada.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"buyer": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com"
},
"fulfillment": {
"methods": [
{
"type": "shipping",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"selected_destination_id": "dest_1"
}
]
},
"payment": {
"selected_instrument_id": "pi_gpay_5678",
"instruments": [
{
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"rich_text_description": "Google Pay •••• 5678"
}
]
}
// ... other fields (line_items, currency, etc.)
}
Respuesta: Vuelves a calcular los impuestos y las opciones de envío según sea necesario, y devuelves el objeto de confirmación de compra completo.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "shipping", "display_text": "Ground Shipping", "amount": 500 },
{ "type": "tax", "amount": 850 },
{ "type": "total", "amount": 11350 }
],
// ... other fields (line_items, currency, etc.)
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1"],
"selected_destination_id": "dest_1",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"total": 500
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"total": 1500
}
]
}
]
}
]
}
}
4. Completa la sesión de confirmación de compra
Este endpoint permite completar una sesión de compra y realizar un pedido. Debe devolver la sesión de compra completada y la información del pedido. El procesamiento del pago debe comenzar después de que se reciba esta llamada.
- Extremo:
POST /checkout-sessions/{id}/complete - Activador: El usuario hace clic en "Realizar pedido".
Solicitud: Google envía el token de pago (BLOB encriptado) del proveedor (p.ej., Google Pay) y indicadores de riesgo sobre el comprador para que realices tu propia detección de fraude.
{
"payment_data": {
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"billing_address": {
"postal_code": "94043",
"address_country": "US"
},
"credential": {
"type": "PAYMENT_GATEWAY",
"token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
}
}
}
Respuesta: Devuelve el objeto de confirmación de compra completo que indica que el pedido está completo, incluido el ID del pedido y la URL de vínculo permanente al pedido.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [...]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "completed",
// ... other fields (line_items, currency, etc.)
"order_id": "gid://merchant.example.com/Order/789",
"order_permalink_url": "https://merchant.example.com/orders/789"
}
5. Cancela la sesión de confirmación de compra
Este endpoint cancela una sesión de confirmación de compra.
- Extremo:
POST /checkout-sessions/{id}/cancel
Solicitud: Google envía el ID de la sesión de confirmación de compra.
Respuesta: Devuelves el objeto de confirmación de compra completo con el estado actualizado a canceled.