네이티브 통합을 사용하려면 Google에서 호출하여 결제 세션을 만들고 관리할 수 있는 RESTful API를 빌드해야 합니다.
전체 흐름은 다음과 같습니다.
- 결제 세션 빌드: 사용자와 선택적으로 에이전트가 세션에 항목을 추가하는 루프에 있습니다.
- Google UI로 핸드오프: 사용자가 결제하기로 결정하면 (참여한 경우) 에이전트가 제어를 Google UI로 전달합니다 (결제 세션 데이터 전달).
- 수동 결제: 이제 사용자는 Google UI와만 상호작용하여 민감한 주문 처리 및 결제 세부정보를 입력하고 주문을 제출합니다. 에이전트는 이 부분에 관여하지 않으므로 결정론이 보장됩니다.
- 완료 및 반환: Google UI에 주문을 확인하는 '감사합니다' 페이지가 표시됩니다. 선택적으로 사용자를 에이전트로 다시 리디렉션할 수 있습니다. 에이전트는 이미 완료된 구매에 대한 알림을 받았을 수 있습니다.
다음 단계에서는 구현해야 하는 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와 주문의 고유 링크 URL을 포함하여 주문이 완료되었음을 나타내는 전체 결제 객체를 반환합니다.
{
"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로 업데이트된 전체 결제 객체를 반환합니다.