토큰 수명 주기 관리 알림

개요

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

MerchantTokenUpdateNotificationRequest

Google Pay Online 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의 마지막 네 문자를 포함하는 네 자리 문자열입니다.

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

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

초기 거래 또는 이전 알림 이후 변경된 경우 토큰의 새 상태입니다.

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

유효한 값은 DISABLED입니다.

MerchantTokenUpdateNotificationResponse

HTTP 응답 코드

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

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

요청의 메시지 ID와 일치해야 합니다. 그렇지 않으면 응답이 무시되고 이 토큰에 대한 향후 알림이 중지됩니다.
status string(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는 tokenUpdateUrl에 토큰 LCM 알림을 전송합니다. 이 기능을 트리거하려면 다음 단계를 따르세요.

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