Implementación de la API de REST de la confirmación de compra nativa

En esta guía, se proporcionan la referencia técnica de la API y los esquemas de cargas útiles para la versión 2026-04-08 de la confirmación de compra nativa del Universal Commerce Protocol (UCP).

Antes de compilar tus extremos, asegúrate de haber revisado la descripción general de la confirmación de compra nativa para conocer el proceso de confirmación de compra de alto nivel, los requisitos de autenticación y las herramientas para desarrolladores.

Crea una sesión de confirmación de compra

Este extremo permite crear una sesión de compra que contiene los productos que un usuario quiere comprar.

  • Endpoint: POST /checkout-sessions
  • Activador: El usuario hace clic en "Comprar ahora" en un producto o en "Confirmar compra en Google" desde el carrito.

Solicitud: Google envía las líneas de pedido y la información de dirección limitada sobre el comprador, que incluye la ciudad, el estado y el código postal.

// Request Example: Create checkout with multiple items.
{
  "line_items": [
    {
      "item": {
        // Must match ID in product feed
        "id": "product_12345"
      },
      "quantity": 1
    },
    {
      "item": {
        // Must match ID in product feed
        "id": "product_67890"
      },
      "quantity": 1
    }
  ],
  "context": {
    "language": "en"
  },
  "fulfillment": {
    "methods": [
      {
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1"
      }
    ]
  }
}

Respuesta: Devuelves la sesión inicializada con los totales, los impuestos (inicialmente estimados) y las capacidades de pago.

Nota sobre el campo ucp.status:

El campo ucp.status, que se introdujo en la versión 2026-04-08, indica el resultado de la creación:

  • "success" (o se omite): Es el valor predeterminado. Se creó la sesión, incluso con messages recuperable.
  • "error": No se pudo crear la sesión debido a un error irrecuperable (p.ej., todos los artículos están agotados). En este caso, el cuerpo de la respuesta debe ser un objeto de respuesta de error, no un objeto de Checkout. Consulta el ejemplo de error irrecuperable en la sección Control de errores.

Nota sobre los cambios en el array totals:

  • El campo type dentro de cada objeto del array totals ahora es una cadena abierta.
  • El campo amount ahora puede ser negativo (p.ej., para representar descuentos).
  • Los objetos en totals (como type: "fee" y type: "tax") pueden incluir, de forma opcional, un array lines para detallar los subcomponentes (p.ej., tarifas de servicio o reciclaje, o desgloses de impuestos provinciales y federales de varios niveles, como el GST, el PST o el QST de Canadá).
  • Precios con impuestos incluidos: En los mercados en los que el precio debe incluir los impuestos aplicables, el atributo subtotal debe incluir el impuesto, se debe omitir el elemento de línea tax y se debe proporcionar explícitamente display_text para las entradas subtotal y fulfillment en totals. Consulta Precios con impuestos incluidos para obtener más detalles.
// Response Example: Initialize Session with multiple items.
{
  "ucp": {
    "version": "2026-04-08",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-04-08", "extends": "dev.ucp.shopping.checkout" } ]
    },
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
          "version": "2026-01-23",
          "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "TEST",
            "merchant_info": {
              "merchant_name": "Example Merchant",
              "merchant_id": "KWMZPRLQFTYNXSDB",
              "merchant_origin": "checkout.merchant.com"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                  "allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
                  "billing_address_required": true,
                  "billing_address_parameters": {
                    "format": "FULL",
                    "phone_number_required": true
                  }
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "example",
                    "gatewayMerchantId": "exampleGatewayMerchantId"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "missing_buyer_info",
      "path": "$.buyer",
      "content_type": "plain",
      "content": "Buyer information is required for checkout",
      "severity": "recoverable"
    },
    {
      "type": "error",
      "code": "missing_fulfillment_info",
      "path": "$.fulfillment.methods[0].destinations[0]",
      "content_type": "plain",
      "content": "Shipping address is incomplete",
      "severity": "recoverable"
    }
  ],
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 10000
        },
        {
          "type": "total",
          "amount": 10000
        }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 2500
        },
        {
          "type": "total",
          "amount": 2500
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal", // Tax-inclusive markets: Set to "Subtotal (including taxes)".
      "amount": 12500 // Tax-inclusive markets: Amount must include tax.
    },
    {
      "type": "fee",
      "display_text": "Fees",
      "amount": 549,
      "lines": [
        { "display_text": "Service Fee", "amount": 399 },
        { "display_text": "Recycling Fee", "amount": 150 }
      ]
    },
    {
      "type": "fulfillment",
      "display_text": "Ground Shipping", // Tax-inclusive markets: Provide display text for fulfillment totals.
      "amount": 500
    },
    {
      "type": "tax", // Tax-inclusive markets: Omit this entry.
      "display_text": "Estimated Tax",
      "amount": 1050
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 14599
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1",
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": [
              "line_1",
              "line_2"
            ],
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ {"type": "total", "amount": 500} ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ {"type": "total", "amount": 1500} ]
              }
            ],
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  },
  "links": [
    {
      "type": "terms_of_service",
      "url": "https://m.com/terms",
      "title": "Terms of Service"
    },
    {
      "type": "privacy_policy",
      "url": "https://m.com/privacy",
      "title": "Privacy Policy"
    }
  ]
}

Precios con impuestos incluidos

En el caso de los mercados en los que el impuesto se incluye en el subtotal que se muestra en lugar de detallarse por separado, tu implementación debe cumplir con los siguientes requisitos cuando proporciones datos de la sesión de confirmación de compra:

  • Incluye el impuesto en el subtotal: El campo amount de la entrada subtotal debe incluir todos los impuestos aplicables.
  • Omite las entradas de impuestos separadas: No incluyas un objeto dedicado con type: "tax" en el array totals.
  • Proporciona texto personalizado para mostrar: Debes incluir un atributo display_text dentro del objeto de subtotal que indique explícitamente que se incluyen los impuestos, como "Subtotal (including taxes)". También debes incluir un atributo display_text para las entradas de cumplimiento (p.ej., "Shipping").

Ejemplo: Array de totales con impuestos incluidos

En el siguiente ejemplo, se muestra un array totals para un comercio en un mercado con impuestos incluidos:

"totals": [
  {
    "type": "subtotal",
    "display_text": "Subtotal (including taxes)",
    "amount": 12500
  },
  {
    "type": "fulfillment",
    "display_text": "Shipping",
    "amount": 399
  },
  {
    "type": "total",
    "display_text": "Total",
    "amount": 12899
  }
]

Desglose de impuestos de varios niveles

En el caso de los mercados que requieren divulgaciones fiscales detalladas de varios niveles o jurisdicciones (como el GST o el HST federales de Canadá y el PST o el QST provinciales), puedes proporcionar un objeto type: "tax" de nivel superior con un array lines anidado:

  • Impuesto agregado de nivel superior: Devuelve un solo objeto tax agregado que contiene el impuesto total amount y una display_text descriptiva (p.ej., "Taxes").
  • Desglose de la línea secundaria: Detalla los componentes fiscales individuales en el array lines con sus respectivos display_text (p.ej., "TPS / GST (5%)", "TVQ / QST (9.975%)") y amount.
  • Invariante: La suma de todos los importes de las líneas secundarias debe ser igual al amount de la entrada tax principal.

Ejemplo: Desglose de impuestos de varios niveles

{
  "type": "tax",
  "display_text": "Taxes",
  "amount": 1498,
  "lines": [
    { "display_text": "TPS / GST (5%)", "amount": 500 },
    { "display_text": "TVQ / QST (9.975%)", "amount": 998 }
  ]
}

Obtén la sesión de confirmación de la compra

Este endpoint permite recuperar una sesión de confirmación de compra.

  • Endpoint: 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. En el caso de una sesión con varios artículos creada en la versión 2026-01-23 o posterior, el array line_items contendrá varias entradas de artículos.

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.

  • Endpoint: PUT /checkout-sessions/{id}

Actualiza la dirección de envío

  • Activador: El usuario selecciona o cambia su dirección de envío.

Solicitud: Google actualiza la dirección de cumplimiento cuando el usuario cambia su dirección de envío.

// Request Example: Update shipping address with multiple items.
{
  "line_items": [
    {
      // line_items id from Create Checkout response
      "id": "line_1",
      "item": {
        "id": "product_12345"
      },
      "quantity": 1
    },
    {
      // line_items id from Create Checkout response
      "id": "line_2",
      "item": {
        "id": "product_67890"
      },
      "quantity": 1
    }
  ],
  "context": {
    "language": "en"
  },
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1",
        "groups": [
          {
            "id": "group_1",
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  }
}

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.

// Response Example: Updated session with new address for multiple items.
{
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 10000 },
        { "type": "total", "amount": 10000 }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 2500 },
        { "type": "total", "amount": 2500 }
      ]
    }
  ],
  "totals": [
     { "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
     // Shipping cost might change based on new address
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
     {
       "type": "fee",
       "display_text": "Fees",
       "amount": 549,
       "lines": [
         { "display_text": "Service Fee", "amount": 399 },
         { "display_text": "Recycling Fee", "amount": 150 }
       ]
     },
     // Tax will likely change based on new address
     { "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14769 }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["line_1", "line_2"],
            "selected_option_id": "ship_ground",
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 600 } ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 1600 } ]
              }
            ]
          }
        ]
      }
    ]
  }
  // ... other fields like ucp, status, messages, links
}

Completar la hidratación del objeto de confirmación de compra

Solicitud: Google envía el objeto de confirmación de compra completo con la información actualizada (incluida la dirección de cumplimiento completa y el contacto del comprador) cuando el comprador hace clic en "Pagar con GPay".

// Request Example: full checkout object hydration for multiple items.
{
  "buyer": {
    "first_name": "John",
    "last_name": "Buyer",
    "email": "johnbuyer@example.com",
    "phone_number": "+18888888888"
  },
  "line_items": [
    {
      "id": "line_1",
      "item": { "id": "product_12345" },
      "quantity": 1
    },
    {
      "id": "line_2",
      "item": { "id": "product_67890" },
      "quantity": 1
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "first_name": "Alice",
            "last_name": "Receiver",
            "street_address": "1600 Amphitheatre Pkwy",
            "extended_address": "Suite #60",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US",
            "phone_number": "+18888888888"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  }
}

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.

// Response Example: Session after full hydration with multiple items.
{
  "ucp": {
    "version": "2026-04-08",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-04-08", "extends": "dev.ucp.shopping.checkout" } ]
    },
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
          "version": "2026-01-23",
          "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "TEST",
            "merchant_info": {
              "merchant_name": "Example Merchant",
              "merchant_id": "KWMZPRLQFTYNXSDB",
              "merchant_origin": "checkout.merchant.com"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                  "allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
                  "billing_address_required": true,
                  "billing_address_parameters": {
                    "format": "FULL",
                    "phone_number_required": true
                  }
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "example",
                    "gatewayMerchantId": "exampleGatewayMerchantId"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "ready_for_complete",
  "currency": "USD",
  "buyer": {
    "first_name": "John",
    "last_name": "Buyer",
    "email": "johnbuyer@example.com",
    "phone_number": "+18888888888"
  },
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 10000 },
        { "type": "total", "amount": 10000 }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 2500 },
        { "type": "total", "amount": 2500 }
      ]
    }
  ],
  "totals": [
     { "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
      {
        "type": "fee",
        "display_text": "Fees",
        "amount": 549,
        "lines": [
          { "display_text": "Service Fee", "amount": 399 },
          { "display_text": "Recycling Fee", "amount": 150 }
        ]
      },
     { "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14769 }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "first_name": "Alice",
            "last_name": "Receiver",
            "street_address": "1600 Amphitheatre Pkwy",
            "extended_address": "Suite #60",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US",
            "phone_number": "+18888888888"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["line_1", "line_2"],
            "selected_option_id": "ship_ground",
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 600 } ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 1600 } ]
              }
            ]
          }
        ]
      }
    ]
  },
  "links": [
    {
      "type": "terms_of_service",
      "url": "https://m.com/terms",
      "title": "Terms of Service"
    },
    {
      "type": "privacy_policy",
      "url": "https://m.com/privacy",
      "title": "Privacy Policy"
    }
  ]
}

Completar 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.

Solicitud: Google envía el instrumento de pago seleccionado desde el controlador de pagos, incluida la credencial (p.ej., datos de tokenización de Google Pay) y los indicadores de riesgo sobre el comprador para que realices tu propia detección de fraude. El contenido del token dependerá de tu proveedor de servicios de pagos.

{
  "payment": {
    "instruments": [
      {
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "100 Main St",
          "extended_address": "Apt 4B",
          "address_locality": "San Francisco",
          "address_region": "CA",
          "postal_code": "94105",
          "address_country": "US",
          "phone_number": "+18888888888"
        },
        "credential": {
          "token": "examplePaymentMethodToken",
          "type": "PAYMENT_GATEWAY"
        },
        "display": {
          "brand": "VISA",
          "description": "Visa •••• 1234",
          "last_digits": "1234"
        },
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
        "selected": true,
        "type": "card"
      }
    ]
  },
  "signals": {
    "com.google.authentication_triggered": "",
    "com.google.authorization_processed_with_3ds": "",
    "com.google.avs_full_result": "",
    "com.google.cvv_result": "",
    "com.google.ip_address": "203.0.113.1",
    "dev.ucp.buyer_id": "ec46fedc6aad89d3660a50a61d00b4908fd160ecf5dda6d49ed41a605c5b180a",
    "dev.ucp.buyer_ip": "203.0.113.1"
  }
}

Si necesitas información obligatoria para completar la confirmación de compra que no se proporcionó en la sesión de confirmación de compra, puedes evitar que se complete la confirmación de compra y solicitar esa información devolviendo un estado no completado en la respuesta.

Si Google puede recopilar la información faltante con los campos definidos por la UCP (por ejemplo, la dirección de correo electrónico del comprador), establece status en incomplete y agrega uno o más mensajes en el array messages con severity establecido en recoverable, lo que indica qué información falta.

{
  "ucp": {
    "version": "2026-04-08",
    "status": "success"
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "missing_buyer_info",
      "severity": "recoverable",
      "content": "Buyer email is required"
    },
    {
      "type": "error",
      "code": "missing_fulfillment_info",
      "severity": "recoverable",
      "content": "Select delivery window for your purchase"
    }
  ]
}

Cuando recibas un instrumento de pago de Google Pay, debes hacer lo siguiente:

  1. Controlador de validación: Confirma que handler_id corresponda al controlador de pagos de Google Pay definido en tu configuración.
  2. Extrae el token: Recupera el token de la forma de pago generada de payment.instruments[0].credential.token.
  3. Procesa el pago: Usa el token y los detalles de la transacción para completar el pago. Consulta la documentación de la API de Google Pay para obtener información detallada sobre la especificación y el control de la tokenización.

Respuesta: Si se puede completar la confirmación de la compra y procesaste el pago, debes devolver el objeto de confirmación de la compra completo que indica que el pedido está completo, incluido el instrumento de pago confirmado (con los metadatos del instrumento y la dirección de facturación, sin el token sensible credential ni signals), el ID del pedido y una URL de vínculo permanente al pedido.

{
  "ucp": {
      "version": "2026-04-08",
      "status": "success",
      "capabilities": [...]
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "completed",

  // ... other fields (line_items, currency, etc.)

  "payment": {
    "instruments": [
      {
        "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "card",
        "selected": true,
        "display": {
          "brand": "VISA",
          "description": "Visa •••• 1234",
          "last_digits": "1234"
        },
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "100 Main St",
          "extended_address": "Apt 4B",
          "address_locality": "San Francisco",
          "address_region": "CA",
          "postal_code": "94105",
          "address_country": "US",
          "phone_number": "+18888888888"
        }
      }
    ]
  },
  "order": {
    "id": "ORD1773956535.2727807",
    // Example customer-facing order number
    "label": "#100",
    "permalink_url": "https://merchant.example.com/orders/789"
  }
}

Cancela la sesión de confirmación de compra

Este endpoint cancela una sesión de compra.

  • Endpoint: 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.

Manejo de errores

Para obtener los lineamientos completos sobre cómo dar formato a los mensajes de error y la distinción entre los errores de protocolo y de lógica empresarial, consulta la Descripción general de los códigos de error.

Error irrecuperable

A partir de la versión 2026-04-08, cuando un error irrecuperable impida la creación de la sesión de confirmación de compra (p.ej., todos los artículos están agotados), se devolverá un 200 OK de HTTP. En el cuerpo de la respuesta, configura "status": "error" dentro del objeto ucp. Esto le indica a Google que la solicitud era válida, pero que una regla de negocio bloqueó la creación de la sesión. En este caso, no se devuelve ningún ID de sesión de confirmación de compra.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-04-08",
    "status": "error"
  },
  "messages": [
    {
      "type": "error",
      "code": "out_of_stock",
      "content": "All requested items are currently out of stock",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://merchant.com/"
}