이 가이드에서는 범용 커머스 프로토콜 (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")에는 하위 구성요소 (예: 서비스 또는 재활용 수수료, 캐나다 GST, PST 또는 QST와 같은 다단계 주 및 연방세 분류)를 항목화하는lines배열이 선택적으로 포함될 수 있습니다.- 세금 포함 가격: 세금 포함 시장의 경우
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)"). 주문 처리 항목 (예:"Shipping")의display_text속성도 포함해야 합니다.
예: 세금 포함 총계 배열
다음 예는 세금 포함 시장의 판매자를 위한 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
}
전체 결제 객체 하이드레이션
요청: 구매자가 '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로 설정하고 severity가 recoverable로 설정된 메시지를 하나 이상 messages 배열에 포함하여 누락된 정보를 나타냅니다.
{
"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, 주문에 대한 고유 링크 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에서 결제 세션의 ID를 전송합니다.
응답: 상태가 canceled로 업데이트된 전체 결제 객체를 반환합니다.
오류 처리
오류 메시지 형식 지정 방법과 프로토콜 오류와 비즈니스 로직 오류의 차이점에 관한 전체 가이드라인은 오류 코드 개요를 참고하세요.
복구 불가 오류
버전 2026-04-08부터 복구할 수 없는 오류로 인해 결제 세션 생성이 방지되는 경우 (예: 모든 상품의 재고가 없음) HTTP 200 OK을 반환합니다. 응답 본문에서 ucp 객체 내에 "status": "error"을 설정합니다.
이는 요청이 유효했지만 비즈니스 규칙으로 인해 세션 생성이 차단되었음을 Google에 알립니다. 이 경우 결제 세션 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/"
}