Thông báo quản lý vòng đời của mã thông báo

Tổng quan

Các thông báo trong tương lai về Quản lý vòng đời (LCM) của mã thông báo sẽ được gửi từ Google Pay Online API đến tokenUpdateUrl được cung cấp tại thời điểm giao dịch ban đầu. Thông báo này sẽ được gửi nếu mã thông báo bị huỷ kích hoạt hoặc bị xoá. Chúng cũng được gửi theo cách tốt nhất có thể với các lần thử lại cho những lần gửi không thành công. Sau đây là ví dụ về quy trình LCM khi người dùng xoá thẻ khỏi Google Wallet:

MerchantTokenUpdateNotificationRequest

Thông báo HTTP POST từ Google Pay Online API, mang theo một phần nội dung JSON bao bọc một tải trọng được mã hoá. Tải trọng được mã hoá bằng khoá mã hoá công khai dùng chung của bạn và được ký bằng khoá riêng tư của Google. Bạn có thể giải mã bằng khoá mã hoá riêng tư và xác minh bằng khoá ký gốc của Google. Định dạng trình bao bọc tải trọng được mã hoá này giống hệt với định dạng mà bạn có thể nhận được dưới dạng PaymentMethodToken. Bạn có thể dùng chính thư viện này để giải mã thông báo LCM này. Trong tải trọng được mã hoá, có một đối tượng MerchantTokenUpdateNotificationRequest như được mô tả chi tiết tại đây.

Thuộc tính Loại Cần thiết Mô tả
messageId chuỗi Bắt buộc

Mã nhận dạng duy nhất của thông báo này để loại bỏ các thông báo trùng lặp và cho mục đích gỡ lỗi.

Nếu không gửi được thông báo này, thì thông báo sẽ vẫn như vậy cho các lần thử lại sau này.
targetNotificationUrl chuỗi Bắt buộc

URL dự kiến cho thông báo này. Bạn phải xác nhận rằng URL này là điểm cuối mà bạn dự định dùng để nhận thông báo LCM của mã thông báo từ Google Pay.
timestamp chuỗi Bắt buộc

Dấu thời gian cho biết thời điểm thông báo này được tạo lần đầu. Giá trị này vẫn giữ nguyên cho các lần thử lại sau này.

Nếu bạn nhận được nhiều thông báo cho cùng một mã thông báo, thì chỉ thông báo có dấu thời gian mới nhất mới được coi là chính xác.
apiVersion int Bắt buộc Phiên bản lớn của API.
apiVersionMinor int Bắt buộc Phiên bản nhỏ của API.
merchantTokenId Chuỗi Bắt buộc Mã thông báo người bán đã được cập nhật. Đây là mã nhận dạng được trả về ban đầu khi người dùng hoàn tất quy trình Google Pay cho MIT. Đây là một trường trong tải trọng được mã hoá, được gửi trong đối tượng Đối tượng Card.
cardUpdateInfo CardUpdateInfo Bắt buộc Chứa nội dung cập nhật cho mã thông báo.

CardUpdateInfo

Thuộc tính Loại Cần thiết Mô tả
fpanSuffix chuỗi Câu lệnh có điều kiện

Nội dung mô tả giúp người dùng xác định Số tài khoản cấp tiền chính (FPAN) cơ bản. Đây là một chuỗi gồm 4 chữ số chứa 4 ký tự cuối cùng của FPAN.

Khi có mặt, trạng thái mã thông báo có thể được giả định là đang hoạt động.

Tham số này sẽ không xuất hiện nếu không có thay đổi.
tokenState string(enum) Câu lệnh có điều kiện

Trạng thái mới của mã thông báo, nếu đã thay đổi kể từ giao dịch ban đầu hoặc thông báo trước đó.

Tham số này sẽ không xuất hiện nếu không có thay đổi.

Giá trị hợp lệ là DISABLED.

MerchantTokenUpdateNotificationResponse

Mã phản hồi HTTP

Mã phản hồi HTTP Cách sử dụng
200 Bạn đã nhận được thông báo. Thông tin bổ sung về trạng thái có thể được cung cấp trong nội dung phản hồi dưới dạng một đối tượng JSON như mô tả trong bảng tiếp theo.
401 targetNotificationUrl trong MerchantTokenUpdateNotificationRequest không hợp lệ. Bạn có thể tắt tất cả thông báo trong tương lai cho mã thông báo này.
5xx Lỗi máy chủ tạm thời. Thông báo này sẽ được gửi lại vào lúc khác.
Khác Lỗi không thể truy xuất. Thông báo này sẽ không được gửi lại vào lúc khác.
Thuộc tính Loại Cần thiết Mô tả
requestMessageId chuỗi Bắt buộc

Mã thông báo được tạo từ yêu cầu.

Giá trị này phải khớp với mã nhận dạng thông báo trong yêu cầu, nếu không, phản hồi có thể bị bỏ qua và các thông báo trong tương lai cho mã thông báo này sẽ bị dừng.
status string(enum) Bắt buộc

Người bán hoặc Nhà cung cấp dịch vụ thanh toán (PSP) có thể trả về một trạng thái phản ánh việc họ tiếp nhận thông báo và việc họ sử dụng mã thông báo.

Các giá trị hợp lệ là:

  • SUCCESS
  • TOKEN_NOT_IN_USE
  • TOKEN_NOT_FOUND

Ví dụ:

Thông báo về vòng đời

Yêu cầu thông báo

Đây là yêu cầu HTTP POST chứa thông báo LCM của mã thông báo, được gửi từ Google Pay đến điểm cuối của bạn. Nội dung là một tải trọng được mã hoá.

Yêu cầu 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\"}"
  }

Decrypted 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"
    }
  }

Phản hồi thông báo

  HTTP 200 OK
  Content-Type: application/json

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

Thử nghiệm bằng điểm cuối tokenUpdateUrl

Ở chế độ KIỂM THỬ, Google Pay sẽ gửi một thông báo LCM mã thông báo đến tokenUpdateUrl của bạn. Để kích hoạt tính năng này, hãy làm theo các bước sau:

  • Hoàn tất một giao dịch kiểm thử bằng cách gọi loadPaymentData bằng một đối tượng *TransactionInfo, điền vào trường tokenUpdateUrl bằng URL điểm cuối của bạn.
  • Dịch vụ của Google sẽ gửi thông báo LCM mã thông báo đến điểm cuối của bạn.
  • Xác minh rằng bạn có thể giải mã thông báo bằng khoá riêng tư của mình. Xin lưu ý rằng ở chế độ TEST, thông báo này sẽ luôn thay đổi 4 chữ số cuối của số thẻ thành "1234" và chứa "tokenState": "DISABLED", bất kể mã thông báo trong yêu cầu.