Google Pay 결제 핸들러 사양

핸들러 이름: com.google.pay
버전: 2026-01-11

1. 소개

com.google.pay 핸들러를 사용하면 비즈니스에서 UCP 호환 플랫폼을 통해 Google Pay를 가속화된 결제 옵션으로 제공할 수 있습니다. Google Pay API를 사용하면 사용자가 Google 계정에 저장된 결제 수단에 액세스할 수 있으므로 빠른 결제가 가능합니다.

이 핸들러는 비즈니스에서 허용된 카드 네트워크 및 게이트웨이 매개변수와 같은 Google Pay 구성을 제공하고 플랫폼에서 Google Pay API와의 클라이언트 측 상호작용을 처리하여 보안 결제 토큰을 생성하는 헤드리스 통합 모델을 지원합니다.

1.1 주요 이점

범용 구성: 비즈니스에서 표준 JSON을 사용하여 Google Pay를 한 번 구성하면 승인된 플랫폼에서 맞춤 프런트엔드 코드 없이 결제 인터페이스를 렌더링할 수 있습니다.
분리된 프런트엔드: 플랫폼은 Google Pay JavaScript API 또는 SDK 통합의 복잡성을 처리하고 비즈니스는 결과 토큰을 사용합니다.
보안 토큰화: Google의 내장 토큰화를 활용하여 암호화된 사용자 인증 정보를 비즈니스의 결제 서비스 제공업체(PSP)에 직접 전달합니다.

2. 비즈니스 통합

2.1 요구사항

UCP를 통해 Google Pay를 광고하려면 비즈니스가 다음 요건을 충족해야 합니다.

Google Pay 판매자 ID 획득: PRODUCTION 환경에서 처리하는 데 필요합니다 (Google Pay 및 월렛 콘솔에 등록).
PSP 지원 확인: 결제 서비스 제공업체 (PSP)가 Google Pay 토큰화의 지원되는 대행업체 및 게이트웨이 목록에 있는지 확인합니다.

2.2 핸들러 구성

비즈니스는 결제 핸들러 배열에 핸들러를 포함하여 Google Pay 지원을 광고합니다. 이 구성은 Google Pay API를 초기화하는 데 필요한 구조를 엄격하게 따릅니다.

2.2.1 구성 스키마

구성 객체는 환경, 비즈니스 ID, 허용된 결제 수단을 정의합니다.

Google Pay 결제 수단

Google Pay의 PaymentMethod에 기반합니다.

토큰화 사양

Google Pay의 TokenizationSpecification을 기반으로 합니다.

2.2.2 핸들러 선언 예시

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "01234567890123456789",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": ["PAN_ONLY"],
                "allowed_card_networks": ["VISA", "MASTERCARD"]
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

2.3 항목

2.3.1 계측기 스키마

Google Pay 수단 (card_payment_instrument)은 기본 카드 결제 수단을 확장합니다. 표준 표시 필드 (예: brand 및 last_digits)를 상속하여 영수증 렌더링의 일관성을 유지하면서 credential 필드를 미세 조정하여 특정 Google Pay 토큰화 페이로드를 전달합니다.

플랫폼 동작: 플랫폼은 Google Pay PaymentMethodData 응답을 이 구조에 매핑한 후 비즈니스에 전송해야 합니다.

이름	유형	필수	설명
id	문자열	예	플랫폼에서 할당한 이 결제 수단의 고유 식별자입니다.
handler_id	문자열	예	Google Pay 핸들러의 식별자입니다.
유형	문자열	예	상수 = `card` 이 결제 수단이 카드처럼 작동함을 나타냅니다 (카드 표시 필드를 상속함).
brand	문자열	예	카드 네트워크 (예: `visa`, `mastercard`). Google Pay의 `info.cardNetwork`에서 매핑됩니다.
last_digits	문자열	예	카드의 마지막 4자리 숫자입니다. Google Pay의 `info.cardDetails`에서 매핑됩니다.
rich_text_description	문자열	아니요	카드의 리치 텍스트 설명 (예: 끝자리가 1234인 Visa 카드, 2025년 12월 만료').
rich_card_art	문자열 (uri)	아니요	카드를 나타내는 리치 이미지의 선택적 URI입니다 (예: 발급기관 카드 아트).
billing_address	우편 주소	아니요	카드와 연결된 청구서 수신 주소입니다.
사용자 인증정보	사용자 인증 정보 페이로드	아니요	Google Pay에서 반환하는 보안 토큰화 데이터입니다.

사용자 인증 정보 페이로드

이 객체는 계측기의 credential 역할을 합니다. Google Pay 토큰화 데이터에 직접 매핑됩니다.

우편 주소

이 객체는 address 필드 역할을 합니다. PostalAddress에 직접 매핑됩니다.

3. 플랫폼 통합

3.1 요구사항

com.google.pay 결제를 처리하기 전에 플랫폼은 다음을 충족해야 합니다.

Google Pay API for Web (또는 Android에 상응하는 API)을 로드할 수 있어야 합니다.
결제 버튼을 렌더링할 때 Google Pay 브랜드 가이드라인을 준수합니다.

3.2 결제 프로토콜

플랫폼은 다음 흐름에 따라 핸들러를 처리해야 합니다(MUST).

1단계: 검색 및 구성

플랫폼은 API 수명 주기를 관리하도록 클라이언트를 초기화합니다.

참조: PaymentsClient

2단계: 결제 준비 상태 확인

플랫폼은 버튼을 표시하기 전에 사용자가 지정된 결제 수단으로 결제할 수 있는지 확인합니다.

참고: isReadyToPay

3단계: 결제 요청 빌드

플랫폼은 판매자 구성, 결제 수단, 거래 세부정보 (가격 및 통화)를 포함한 결제 데이터 요청 객체를 어셈블합니다.

참조: PaymentDataRequest

4단계: 사용자 상호작용 호출

사용자가 결제 버튼과 상호작용하면 플랫폼에서 결제 시트 표시를 트리거합니다.

참조: loadPaymentData

5단계: 결제 완료

사용자 상호작용이 성공하면 Google Pay API가 payment_data 키 아래에 PaymentInstrument 객체를 반환합니다. 플랫폼은 이 응답을 card_payment_instrument 스키마에 매핑하고 결제 완료 요청을 제출합니다.

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "brand": "visa",
    "last_digits": "4242",
    "billing_address": {
      "street_address": "123 Main Street",
      "extended_address": "Suite 400",
      "address_locality": "Charleston",
      "address_region": "SC",
      "postal_code": "29401",
      "address_country": "US",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

4. 비즈니스 처리

Google Pay 결제 수단을 수신한 비즈니스는 다음을 충족해야 합니다(MUST).

핸들러 유효성 검사: handler_id이 Google Pay 핸들러에 해당하는지 확인합니다.
토큰 추출: payment_data.credential.token에서 토큰 문자열을 가져옵니다.
결제 처리: 토큰 문자열과 거래 세부정보를 PSP의 엔드포인트에 전달합니다.
- 참고: 대부분의 PSP에는 'Google Pay 페이로드' 또는 '네트워크 토큰'을 위한 특정 필드가 있습니다.
반환 응답: 최종 결제 상태(성공/실패)로 응답합니다.

5. 보안 고려사항

5.1 토큰 보안

PAYMENT_GATEWAY: 이 토큰화 유형을 사용하면 토큰이 토큰화 당사자를 위해 특별히 암호화됩니다. 통과 당사자는 이 토큰을 복호화할 수 없으며 토큰화 당사자에게 그대로 전달해야 합니다.
직접: DIRECT 토큰화를 사용하는 경우 비즈니스는 복호화해야 하는 암호화된 카드 데이터를 수신합니다. 이렇게 하면 PCI DSS 규정 준수 범위가 크게 늘어나며, 비즈니스가 Level 1 PCI 규정 준수 서비스 제공업체가 아닌 경우 일반적으로 권장되지 않습니다.

5.2 환경 격리

테스트 모드: TEST 환경에서 Google Pay는 더미 토큰을 반환합니다. 이러한 항목에는 요금이 청구되지 않습니다.
프로덕션 모드: 실제 카드가 사용됩니다. 비즈니스에서 config.allowed_payment_methods의 PSP 사용자 인증 정보가 환경과 일치하는지 확인해야 합니다.

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