내장 결제 기능

내장 결제 통합을 사용하면 웹 기반 결제를 Google 서비스에 삽입할 수 있습니다. 제품에 네이티브 API에서 지원할 수 없는 복잡한 로직 (예: 맞춤설정)이 필요한 경우 이 경로를 사용하세요. iframe을 통해 결제 흐름에 삽입될 결제 UI를 구현합니다.

내장 결제란 무엇인가요?

삽입된 결제(EC)를 사용하면 호스트(예: Google 검색 또는 AI 에이전트)가 iframe 또는 WebView를 사용하여 애플리케이션 내에 기존 웹 기반 결제를 표시할 수 있습니다. 표준 웹 리디렉션과 달리 양방향 통신이 가능합니다. 호스트는 저장된 주소를 선택하거나 저장된 사용자 인증 정보로 결제하는 등의 특정 작업을 '위임'하여 더 빠르고 네이티브한 환경을 제공할 수 있으며, 귀하는 기록상의 판매자로 남아 실제 주문 생성을 처리합니다.

판매자 구현 체크리스트

삽입된 결제를 지원하려면 UCP API와 프런트엔드 결제 애플리케이션에서 다음 요구사항을 구현해야 합니다.

1. 탐색 사용 설정 (UCP API)

UCP API 응답에서 결제에 삽입된 확장 프로그램이 지원된다고 선언해야 합니다.

작업: UCP 응답 기능 배열에 dev.ucp.shopping.embedded_checkout 기능 객체를 추가합니다.
요구사항: 사양 및 스키마 URL을 포함합니다.
선택사항: 결제 페이지를 로드하는 데 인증 (예: JWT 토큰)이 필요한 경우 auth.required을 true로 설정합니다.

"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. URL 초기화 처리 (프런트엔드)

호스트가 continue_url를 로드하면 특정 쿼리 매개변수가 추가됩니다. 프런트엔드는 로드 시 이러한 값을 즉시 파싱해야 합니다.

작업: 다음 URL 쿼리 매개변수를 파싱합니다.
- ec_version: 프로토콜 버전입니다 (예: 2026-01-11))를 제공합니다.
- ec_auth: (해당하는 경우) auth.required: true을 설정한 경우 호스트에서 제공한 인증 토큰을 검증합니다.
- ec_delegate: 호스트가 네이티브로 처리하려는 작업의 쉼표로 구분된 목록입니다 (예: payment.credential, fulfillment.address_change, payment.instruments_change)의 파일에만 라벨을 지정할 수 있습니다.

3. 통신 설정 (프런트엔드)

통신은 JSON-RPC 2.0 형식을 사용하여 postMessage를 통해 이루어집니다.

작업: message 이벤트의 리스너를 구현합니다.
요구사항: 모든 메시지의 출처가 호스트와 일치하는지 확인해야 합니다.
네이티브 지원: 네이티브 앱 호스트의 경우 삽입된 전역 변수 (예: postMessage을 사용할 수 없는 경우 window.EmbeddedCheckoutProtocolConsumer을 사용합니다.

4. 핸드셰이크 실행 (프런트엔드)

결제가 렌더링되는 즉시 호스트에 준비가 되었음을 알리고 수락할 위임을 확인해야 합니다.

작업: 로드 후 즉시 ec.ready 요청을 전송합니다.
페이로드: 호스트가 처리하도록 허용하는 기능이 나열된 delegate 배열을 포함합니다.
예: 요청된 URL이 ec_delegate=payment.credential이고 이를 수락하는 경우 ec.ready 페이로드에 "payment.credential"을 포함합니다.

// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential"] // List capabilities you accept to delegate
  }
}), "*");

5. 위임 로직 구현 (프런트엔드)

핸드셰이크에서 위임을 수락한 경우 충돌을 방지하도록 UI 동작을 수정해야 합니다.

작업: 위임된 작업과 관련된 UI 요소를 숨깁니다.
예: fulfillment.address_change가 위임된 경우 주소 양식을 숨기고 대신 '주소 변경' 버튼을 표시합니다.
작업: 사용자가 이 버튼을 클릭하면 _request 메시지를 전송합니다(예: ec.fulfillment.address_change_request)를 호스트에 전송합니다.
작업: 호스트의 응답을 기다립니다. 응답에는 새 데이터 (예: 선택한 주소)가 포함됩니다.
요구사항: 호스트에서 반환된 데이터를 기반으로 PUT 스타일 교체(전체 객체 섹션 교체)를 사용하여 결제 상태를 업데이트합니다.

// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "ec.payment.credential_request",
  "params": {
      "checkout": currentCheckoutState // Pass the full current checkout object
  }
}), "*");

6. 수명 주기 및 상태 업데이트 전송 (프런트엔드)

호스트가 UI를 업데이트하거나 오류를 처리할 수 있도록 결제 상태를 호스트에게 알려야 합니다.

작업: 상태가 변경될 때 알림 (ID가 없는 메시지)을 전송합니다.
- ec.start: 결제가 완전히 표시되는 경우입니다.
- ec.line_items.change: 장바구니 콘텐츠 또는 합계가 업데이트되는 경우
- ec.buyer.change: 구매자 세부정보가 업데이트된 경우
- ec.complete: 주문이 완료된 경우
- ec.error: 심각한 오류가 발생한 경우

7. 보안 적용 (서버/헤더)

악의적인 행위자가 결제를 삽입할 수 없도록 해야 합니다.

작업: 콘텐츠 보안 정책 (CSP) 헤더를 구현합니다.
요구사항: 신뢰할 수 있는 호스트만 삽입할 수 있도록 frame-ancestors <host_origin>;를 설정합니다.
탐색: 사용자가 결제 흐름에서 벗어나도록 유도하는 로직을 차단합니다 (예: 홈페이지로 연결되는 '쇼핑 계속하기' 링크 삭제). 3DS 인증 또는 서드 파티 결제 리디렉션의 경우 예외가 허용됩니다.

내장 결제 기능 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.