토큰 수명 주기 관리 알림

개요

향후 토큰 LCM (수명 주기 관리) 알림은 Google Pay 온라인 API에서 원래 트랜잭션 시 제공된 tokenUpdateUrl 로 전송됩니다. 토큰이 비활성화되거나 삭제되면 전송됩니다. 또한 전송 실패 시 재시도와 함께 최선을 다해 전송됩니다. 다음은 사용자가 Google 월렛에서 카드를 삭제할 때의 LCM 흐름 예입니다.

MerchantTokenUpdateNotificationRequest

Google Pay 온라인 API의 HTTP POST 메시지는 암호화된 페이로드를 캡슐화하는 JSON 본문을 전달합니다. 페이로드는 공유된 공개 암호화 키로 암호화되고 Google의 비공개 키로 서명됩니다. 비공개 암호화 키로 복호화하고 Google의 루트 서명 키로 확인할 수 있습니다. 이 암호화된 페이로드 래퍼 형식은 PaymentMethodToken으로 수신할 수 있는 형식과 동일합니다. 동일한 라이브러리를 사용하여 이 LCM 알림을 복호화할 수 있습니다. 암호화된 페이로드 내에는 여기에 자세히 설명된 MerchantTokenUpdateNotificationRequest 객체 가 있습니다.

속성 유형 필요성 설명
messageId 문자열 필수

메시지 중복 삭제 및 디버깅을 위한 이 알림의 고유 ID입니다.

이 알림이 전송되지 않으면 향후 재시도에서도 동일하게 유지됩니다.
targetNotificationUrl 문자열 필수

이 알림의 대상 URL입니다. 이 URL이 Google Pay에서 토큰 LCM 알림을 수신할 대상 엔드포인트인지 확인해야 합니다.
timestamp 문자열 필수

이 알림이 처음 생성된 타임스탬프입니다. 향후 재시도에서도 동일하게 유지됩니다.

동일한 토큰 ID에 대해 여러 알림을 수신하는 경우 가장 최근 타임스탬프가 있는 알림만 정확한 것으로 간주됩니다.
apiVersion int 필수 API 주 버전입니다.
apiVersionMinor int 필수 API 부 버전입니다.
merchantTokenId 문자열 필수 업데이트가 포함된 판매자 토큰 ID입니다. 사용자가 MIT의 Google Pay 흐름을 완료했을 때 원래 반환된 ID입니다. 암호화된 페이로드 내의 필드입니다. Card 객체.
cardUpdateInfo CardUpdateInfo 필수 토큰 업데이트를 포함합니다.

CardUpdateInfo

속성 유형 필요성 설명
fpanSuffix 문자열 조건부

사용자가 기본 FPAN (Funding Primary Account Number)을 식별하는 데 도움이 되는 설명입니다. FPAN의 마지막 4자를 포함하는 4자리 문자열입니다.

이 문자열이 있으면 토큰 상태가 활성 상태인 것으로 간주할 수 있습니다.

변경사항이 없으면 표시되지 않습니다.
tokenState 문자열(enum) 조건부

초기 트랜잭션 또는 이전 알림 이후 변경된 경우 토큰의 새 상태입니다.

변경사항이 없으면 표시되지 않습니다.

유효한 값은 DISABLED입니다.

MerchantTokenUpdateNotificationResponse

HTTP 응답 코드

HTTP 응답 코드 사용
200 알림이 수신되었습니다. 다음 표에 설명된 대로 응답 본문에 JSON 객체로 추가 상태 정보를 제공할 수 있습니다.
401 MerchantTokenUpdateNotificationRequest 의 targetNotificationUrl이 잘못되었습니다. 이 토큰의 향후 모든 알림을 사용 중지할 수 있습니다.
5xx 일시적인 서버 오류입니다. 나중에 알림을 다시 보내야 합니다.
기타 재시도할 수 없는 오류입니다. 나중에 알림을 다시 보내면 안 됩니다.
속성 유형 필요성 설명
requestMessageId 문자열 필수

요청에서 생성된 메시지 ID입니다.

요청의 메시지 ID와 일치해야 합니다. 그렇지 않으면 응답이 무시되고 이 토큰의 향후 알림이 중지됩니다.
status 문자열(enum) 필수

판매자 또는 결제 서비스 제공업체 (PSP)는 알림 수집 및 토큰 사용을 반영하는 상태를 반환할 수 있습니다.

유효한 값은 다음과 같습니다.

  • SUCCESS
  • TOKEN_NOT_IN_USE
  • TOKEN_NOT_FOUND

예

수명 주기 알림

알림 요청

Google Pay에서 엔드포인트로 전송되는 토큰 LCM 알림이 포함된 HTTP POST 요청입니다. 본문은 암호화된 페이로드입니다.

HTTP 요청

  HTTP POST /token/notification/123
  Host: api.merchant.com
  Content-Type: application/json

  {
    "protocolVersion":"ECv2",
    "signature":"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\u003d\u003d",
    "intermediateSigningKey":{
      "signedKey": "{\"keyExpiration\":\"1542323393147\",\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw\\u003d\\u003d\"}",
      "signatures": ["MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v"]
    },
    "signedMessage":"{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\u003d\",\"ephemeralPublicKey\":\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\u003d\",\"encryptedMessage\":\"mKOoXwi8OavZ\"}"
  }

복호화된 MerchantTokenUpdateNotificationRequest

  {  // MerchantTokenUpdateNotificationRequest
    "messageId": "ZlxoWhLC3su",
    "targetNotificationUrl":
      "https://api.merchant.com/token/notification/123",
    "timestamp": "2025-03-28T07:53:12.39Z",
    "apiVersion": 1,
    "apiVersionMinor": 0,
    "merchantTokenId": "123",
    "cardUpdateInfo": {
      "tokenState": "DISABLED"
    }
  }

알림 응답

  HTTP 200 OK
  Content-Type: application/json

  {  // MerchantTokenUpdateNotificationResponse
    "requestMessageId": "ZlxoWhLC3su",
    "status": "SUCCESS",
  }

tokenUpdateUrl 엔드포인트로 테스트

테스트 모드에서 Google Pay는 토큰 LCM 알림을 tokenUpdateUrl로 전송합니다. 이를 트리거하려면 다음 단계를 따르세요.

  • *TransactionInfo 객체로 loadPaymentData를 호출하여 테스트 트랜잭션을 완료하고 tokenUpdateUrl 필드를 엔드포인트 URL로 채웁니다.
  • Google 서비스가 토큰 LCM 알림을 엔드포인트로 전송합니다.
  • 비공개 키를 사용하여 알림을 복호화할 수 있는지 확인합니다. 테스트 모드에서는 이 알림이 항상 카드 번호의 마지막 4자리를 "1234"로 변경하고 "tokenState": "DISABLED" 요청의 토큰과 관계없이 포함합니다.