本指南提供了版本 2026-04-08 的通用商务协议 (UCP) 原生结账功能的技术 API 参考文档和载荷架构。
在构建端点之前，请务必查看原生结账概览，了解大致的结账流程、身份验证要求和开发者工具。
创建结账会话
此端点允许创建包含用户有意购买的商品的结账会话。
- 端点：
POST /checkout-sessions - 触发条件：用户点击商品上的“立即购买”或购物车中的“在 Google 上结账”。
请求：Google 会发送订单项以及买家的有限地址信息，包括城市、省/直辖市/自治区和邮政编码。
// 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"
}
]
}
}
响应：您返回已初始化的会话，其中包含总金额、税费（最初为估算值）和付款功能。
关于 ucp.status 字段的说明：
ucp.status 字段是在版本 2026-04-08 中引入的，用于指示创建结果：
"success"（或省略）：默认值。即使存在可恢复的messages，也已创建会话。"error"：由于出现无法恢复的错误（例如，所有商品均缺货），会话创建失败。在这种情况下，响应正文应为错误响应对象，而不是结账对象。请参阅“错误处理”部分中的不可恢复的错误示例。
关于 totals 数组更改的说明：
totals数组中每个对象内的type字段现在是一个开放式字符串。amount字段现在可以为负数（例如，表示折扣）。totals中的对象（例如type: "fee"和type: "tax"）可以选择性地包含lines数组，以详细列出子组件（例如服务费或回收费，或多层级的省和联邦税费细分，如加拿大 GST、PST 或 QST）。- 含税价格：对于价格含税的市场，
subtotal必须包含税费，应省略tax明细项，并且应在totals中为subtotal和fulfillment条目明确提供display_text。如需了解详情，请参阅含税价格。
// 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"
}
]
}
含税价格
对于税费包含在所显示的小计中（而不是单独列出）的市场，您在提供结账会话数据时，必须遵循以下实现要求：
- 在小计中包含税费：
subtotal条目的amount字段必须包含所有适用税费。 - 省略单独的税费条目：请勿在
totals数组中添加包含type: "tax"的专用对象。 - 提供自定义显示文本：您必须在小计对象中添加
display_text属性，明确说明税费已包含在内，例如"Subtotal (including taxes)"。您还必须为执行方式条目添加display_text属性（例如"Shipping"）。
示例：含税总额数组
以下示例展示了含税市场中商家的 totals 数组：
"totals": [
{
"type": "subtotal",
"display_text": "Subtotal (including taxes)",
"amount": 12500
},
{
"type": "fulfillment",
"display_text": "Shipping",
"amount": 399
},
{
"type": "total",
"display_text": "Total",
"amount": 12899
}
]
多层级税费明细
对于需要提供分项多级或多管辖区税务披露信息（例如加拿大联邦 GST 或 HST 以及省 PST 或 QST）的市场，您可以提供包含嵌套 lines 数组的顶级 type: "tax" 对象：
- 汇总顶级税费：返回一个包含总税费
amount和描述性display_text（例如"Taxes"）的单个汇总tax对象。 - 子行细分：在
lines数组中列出各个税费组成部分，并提供各自的display_text（例如"TPS / GST (5%)"、"TVQ / QST (9.975%)"）和amount。 - 不变量：所有子行金额的总和必须等于父级
tax条目的amount。
示例：多级税费细分
{
"type": "tax",
"display_text": "Taxes",
"amount": 1498,
"lines": [
{ "display_text": "TPS / GST (5%)", "amount": 500 },
{ "display_text": "TVQ / QST (9.975%)", "amount": 998 }
]
}
获取结账会话
此端点允许检索结账会话。
- 端点：
GET /checkout-sessions/{id}
请求：Google 会发送结账会话的 ID。如果您使用全局 ID（例如 gid://merchant.example.com/Checkout/session_abc123），请注意，请求路径中的 ID 将仅是此 ID 的最后一个组成部分（例如 session_abc123）。
响应：您返回完整的结账对象。对于在版本 2026-01-23 或更高版本下创建的多项会话，line_items 数组将包含多个商品条目。
更新结账会话
此端点允许更新结账会话。更新送货地址时，必须重新计算并返回税费和配送选项。
- 端点：
PUT /checkout-sessions/{id}
更新送货地址
- 触发条件：用户选择或更改送货地址。
请求：当用户更改送货地址时，Google 会更新履单地址。
// 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"
}
]
}
]
}
}
响应：您根据需要重新计算税费和运费选项，并返回完整的结账对象。
// 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
}
完整的结账对象水合
请求：当买家点击“使用 GPay 付款”时，Google 会发送包含更新后信息的完整结账对象（包括完整配送地址和买家联系信息）。
// 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"
}
]
}
]
}
}
响应：您根据需要重新计算税费和运费选项，并返回完整的结账对象。
// 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"
}
]
}
完成结账会话
此端点用于完成结账会话并下单。它应返回已完成的结账会话，并包含订单信息。收到此调用后，应立即开始处理付款。
- 端点：
POST /checkout-sessions/{id}/complete - 触发条件：用户点击“使用 GPay 付款”，并且 Google 从完全水合的结账更新中收到成功响应。
请求：Google 会从付款处理程序发送所选付款方式，包括凭据（例如 Google Pay 令牌化数据）和买家的风险信号，以便您自行进行欺诈检测。令牌内容将取决于您的支付服务提供商。
{
"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"
}
}
如果您需要用户提供结账会话中未提供的强制性信息才能完成结账，则可以在响应中返回不完整的状态，以阻止完成结账并请求用户提供相应信息。
如果 Google 可以使用 UCP 定义的字段（例如买家的电子邮件地址）收集缺失的信息，请将 status 设置为 incomplete，并在 messages 数组中添加一条或多条消息，并将 severity 设置为 recoverable，以指明缺少哪些信息。
{
"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"
}
]
}
收到 Google Pay 支付方式后，您必须：
- 验证处理程序：确认
handler_id与配置中定义的 Google Pay 支付处理程序相对应。 - 提取支付标记：从
payment.instruments[0].credential.token中检索生成的支付方式支付标记。 - 处理付款：使用令牌和交易详情完成付款。如需详细了解令牌化规范和处理，请参阅 Google Pay API 文档。
响应：如果可以完成结账并且您已处理付款，则返回完整的结账对象，指明订单已完成，包括已确认的支付方式（回显方式元数据和账单邮寄地址，但不包含敏感的 credential 令牌或 signals）、订单 ID 和订单的永久链接网址。
{
"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"
}
}
取消结账会话
此端点用于取消结账会话。
- 端点：
POST /checkout-sessions/{id}/cancel
请求：Google 会发送结账会话的 ID。
响应：您返回完整的结账对象，并将状态更新为 canceled。
错误处理
如需查看有关如何设置错误消息格式以及协议错误与业务逻辑错误之间区别的完整指南，请参阅错误代码概览。
不可恢复的错误
从版本 2026-04-08 开始，当出现不可恢复的错误导致无法创建结账会话时（例如，所有商品均缺货），返回 HTTP 200 OK。在响应正文中，在 ucp 对象内设置 "status": "error"。这表示请求有效，但业务规则阻止了会话创建。在这种情况下，不会返回结账会话 ID。
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/"
}