คู่มือนี้มีข้อมูลอ้างอิงทางเทคนิคของ API และสคีมาเพย์โหลดสำหรับเวอร์ชัน
2026-04-08ของการชำระเงินเนทีฟของ Universal Commerce Protocol (UCP)
ก่อนสร้างปลายทาง โปรดตรวจสอบว่าคุณได้อ่านภาพรวมการชำระเงินภายในระบบเพื่อดูขั้นตอนการชำระเงินระดับสูง ข้อกำหนดในการตรวจสอบสิทธิ์ และเครื่องมือสำหรับนักพัฒนาแอป
สร้างเซสชันการชำระเงิน
ปลายทางนี้อนุญาตให้สร้างเซสชันการชำระเงินที่มีผลิตภัณฑ์ที่ผู้ใช้สนใจซื้อ
- ปลายทาง:
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
- ตอนนี้ฟิลด์
typeภายในแต่ละออบเจ็กต์ในอาร์เรย์totalsเป็นสตริงแบบเปิด แล้ว - ตอนนี้ฟิลด์
amountสามารถเป็นค่าลบได้แล้ว (เช่น เพื่อแสดงส่วนลด) - ออบเจ็กต์ใน
totals(เช่นtype: "fee"และtype: "tax") อาจมีอาร์เรย์linesเพื่อแสดงรายการคอมโพเนนต์ย่อย (เช่น ค่าธรรมเนียมบริการหรือ ค่าธรรมเนียมการรีไซเคิล หรือการแยกย่อยภาษีระดับรัฐและระดับรัฐบาลกลางแบบหลายระดับ เช่น GST, PST หรือ QST ของแคนาดา) - การกำหนดราคาแบบรวมภาษี: สำหรับตลาดที่รวมภาษี
subtotalต้อง รวมภาษี ไม่ควรระบุรายการบรรทัดtaxและควรระบุdisplay_textอย่างชัดเจนสำหรับรายการsubtotalและfulfillmentในtotalsดูรายละเอียดได้ที่การกำหนดราคารวมภาษี
// 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"
}
]
}
การกำหนดราคารวมภาษี
สำหรับตลาดที่รวมภาษีไว้ในยอดรวมย่อยที่แสดงแทนที่จะแสดงแยกรายการ ต่างหาก การติดตั้งใช้งานของคุณต้องเป็นไปตามข้อกำหนดต่อไปนี้เมื่อ ระบุข้อมูลเซสชันการชำระเงิน
- รวมภาษีในยอดรวมย่อย: ฟิลด์
amountสำหรับรายการsubtotalต้องรวมภาษีที่เกี่ยวข้องทั้งหมด - ละเว้นรายการภาษีแยกต่างหาก: อย่ารวมออบเจ็กต์เฉพาะที่มี
type: "tax"ในอาร์เรย์totals - ระบุข้อความที่กำหนดเองที่จะแสดง: คุณต้องระบุ
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ที่เกี่ยวข้อง - ค่าคงที่: ผลรวมของจำนวนเงินในบรรทัดย่อยทั้งหมดต้องเท่ากับ
amountของtaxรายการหลัก
ตัวอย่าง: รายละเอียดภาษีหลายระดับ
{
"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 ส่งรหัสของเซสชันการชำระเงิน หากคุณใช้รหัสส่วนกลาง
(เช่น gid://merchant.example.com/Checkout/session_abc123) โปรดทราบว่ารหัส
ในเส้นทางการขอจะเป็นเพียงคอมโพเนนต์สุดท้ายของรหัสนี้ (เช่น
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
}
Hydration ของออบเจ็กต์การชำระเงินทั้งหมด
คำขอ: Google จะส่งออบเจ็กต์การชำระเงินทั้งหมดพร้อมข้อมูลที่อัปเดตแล้ว (รวมถึงที่อยู่การจัดการทั้งหมดและข้อมูลติดต่อของผู้ซื้อ) เมื่อผู้ซื้อ คลิก "ชำระเงินด้วย 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"
}
]
}
]
}
}
การตอบกลับ: คุณคำนวณภาษีและตัวเลือกการจัดส่งใหม่ตามที่จำเป็น แล้วส่งคืน ออบเจ็กต์การชำระเงินทั้งหมด
// 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 และรวมข้อความอย่างน้อย 1 รายการในอาร์เรย์ 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 ที่ละเอียดอ่อน) รหัสคำสั่งซื้อ และ
URL ของลิงก์ถาวรไปยังคำสั่งซื้อ
{
"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 ส่งรหัสของเซสชันการชำระเงิน
การตอบกลับ: คุณส่งคืนออบเจ็กต์การชำระเงินทั้งหมดพร้อมสถานะที่อัปเดตเป็น
canceled
การจัดการข้อผิดพลาด
ดูหลักเกณฑ์ทั้งหมดเกี่ยวกับวิธีจัดรูปแบบข้อความแสดงข้อผิดพลาดและความแตกต่าง ระหว่างข้อผิดพลาดของโปรโตคอลและตรรกะทางธุรกิจได้ที่ภาพรวมรหัสข้อผิดพลาด
ข้อผิดพลาดที่กู้คืนไม่ได้
ตั้งแต่เวอร์ชัน 2026-04-08 เป็นต้นไป เมื่อข้อผิดพลาดที่กู้คืนไม่ได้ทำให้สร้างเซสชันการชำระเงินไม่ได้ (เช่น สินค้าทั้งหมดหมดสต็อก) ให้แสดง HTTP 200 OK ในเนื้อหาการตอบกลับ ให้ตั้งค่า "status": "error" ภายในออบเจ็กต์ ucp
ซึ่งจะบอก Google ว่าคำขอถูกต้อง แต่กฎทางธุรกิจบล็อกการสร้างเซสชัน ในกรณีนี้ ระบบจะไม่แสดงรหัสเซสชันการชำระเงิน
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/"
}