本指南提供通用商務通訊協定 (UCP) 原生結帳功能 2026-04-08 版的技術 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」欄位注意事項：
2026-04-08 版開始提供的 ucp.status 欄位會指出建立結果：
"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)，您可以提供頂層 type: "tax" 物件，其中包含巢狀 lines 陣列：
- 匯總頂層稅金：傳回單一匯總
tax物件，其中包含總稅金amount和說明性display_text(例如"Taxes")。 - 子行細目：在
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
}
完整結帳物件補水
要求：買家點選「使用 Google Pay 付款」時，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 - 觸發條件：使用者點選「使用 Google Pay 付款」，且 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/"
}