原生集成要求您构建一个 RESTful API，供 Google 调用以创建和管理结账会话。
整体流程如下：
- 构建结账会话：用户（可选）和代理在一个循环中向会话添加商品。
- 切换到 Google 界面：用户决定结账后，代理（如果已参与对话）会将控制权传递给 Google 界面（传递结账会话数据）
- 手动结账：用户现在仅与 Google 界面互动，以填写敏感的履单和付款详细信息并提交订单。代理不参与此部分，从而确保确定性。
- 完成和返回：Google 界面会显示“谢谢”页面，以确认订单。用户也可以选择重定向回代理，代理可能已经收到购买完成的通知。
以下步骤介绍了您需要实现的 API 端点及其行为。
1. 创建结账会话
此端点允许创建包含用户有意购买的商品的结账会话。
- 端点：
POST /checkout-sessions - 触发条件：用户点击商品上的“购买”按钮。
请求：Google 会发送订单项和币种。
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
响应：您返回已初始化的会话，其中包含总金额、税费（最初为估算值）和付款功能。您必须添加指向服务条款和隐私权政策的链接，这些链接将显示在付款按钮下方。
{
"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. 获取结账会话
此端点允许检索结账会话。
- 端点：
GET /checkout-sessions/{id}
请求：Google 会发送结账会话的 ID。如果您使用全局 ID（例如 gid://merchant.example.com/Checkout/session_abc123），请注意，请求路径中的 ID 将仅是此 ID 的最后一个组成部分（例如，session_abc123）。
响应：您返回完整的结账对象。
3. 更新结账会话
此端点允许更新结账会话。更新送货地址后，必须重新计算并返回税费和运费选项。
- 端点：
PUT /checkout-sessions/{id} - 触发条件：用户选择或更改送货地址、更新送货选择或更新付款信息。
请求：Google 会发送包含更新后信息的完整结账对象。
{
"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.)
}
响应：您根据需要重新计算税费和运费选项，然后返回完整的结账对象。
{
"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. 完成结账会话
此端点允许完成结账会话并下单。它应返回已完成的结账会话，并包含订单信息。收到此调用后，应立即开始处理付款。
- 端点：
POST /checkout-sessions/{id}/complete - 触发条件：用户点击“下单”。
请求：Google 会发送来自提供商（例如 Google Pay），以及买家的风险信号，以便您自行检测欺诈行为。
{
"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\"...}"
}
}
}
响应：您返回完整的结账对象，指明订单已完成，其中包括订单 ID 和指向订单的永久链接网址。
{
"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. 取消结账会话
此端点用于取消结账会话。
- 端点：
POST /checkout-sessions/{id}/cancel
请求：Google 会发送结账会话的 ID。
响应：您返回完整的结账对象，并将状态更新为 canceled。