اعلان‌های مدیریت چرخه حیات توکن

نمای کلی

اعلان‌های «مدیریت چرخه حیات» (LCM) توکن‌های آینده از Google Pay Online API به tokenUpdateUrl ارائه‌شده در زمان تراکنش اصلی ارسال می‌شود. اگر توکنی غیرفعال یا حذف شود، این اعلان‌ها ارسال می‌شوند. این اعلان‌ها همچنین با حداکثر تلاش ممکن ارسال می‌شوند و درصورت عدم تحویل، دوباره ارسال می‌شوند. در اینجا نمونه‌ای از جریان LCM را وقتی کارتی توسط کاربر از «کیف پول Google» برداشته می‌شود می‌بینید:

MerchantTokenUpdateNotificationRequest

پیام HTTP POST از Google Pay Online API، حاوی یک بدنه JSON است که یک بار مفید رمزگذاری‌شده را کپسوله می‌کند. بار داده با کلید رمزگذاری عمومی هم‌رسانی‌شده شما رمزگذاری شده است و با کلید خصوصی Google امضا شده است. می‌توانید با کلید رمزگذاری خصوصی‌تان رمزگشایی کنید و با کلید امضای ریشه Google درستی‌سنجی کنید. این قالب پوشاننده محموله رمزگذاری‌شده با آنچه ممکن است به‌عنوان PaymentMethodToken دریافت کنید یکسان است. می‌توانید از همان کتابخانه برای رمزگشایی این اعلان LCM استفاده کنید. در محموله رمزگذاری‌شده، یک شیء MerchantTokenUpdateNotificationRequest وجود دارد که جزئیات آن در اینجا آمده است.

دارایی نوع ضرورت شرح
messageId رشته الزامی

شناسه یکتای این اعلان برای حذف پیام‌های تکراری و برای اهداف اشکال‌زدایی.

اگر این اعلان با موفقیت ارسال نشود، برای تلاش‌های مجدد بعدی نیز همین‌طور باقی می‌ماند.
targetNotificationUrl رشته الزامی

نشانی وب موردنظر برای این اعلان. باید تأیید کنید که این نشانی وب نقطه پایانی موردنظر شما برای دریافت اعلان‌های LCM توکن از Google Pay است.
timestamp رشته الزامی

مُهر زمان مربوط به زمانی که این اعلان در ابتدا ایجاد شده است. این مقدار برای تلاش‌های مجدد بعدی یکسان باقی می‌ماند.

اگر برای یک شناسه داده‌واحد چندین اعلان دریافت کنید، فقط اعلانی که جدیدترین مُهر زمان را دارد دقیق درنظر گرفته می‌شود.
apiVersion قطع توپ الزامی نسخه عمده میانای برنامه‌سازی کاربردی.
apiVersionMinor قطع توپ الزامی نسخه جزئی میانای برنامه‌سازی کاربردی.
merchantTokenId رشته الزامی شناسه کد فروشنده با به‌روزرسانی. این شناسه‌ای است که در ابتدا وقتی کاربر جریان Google Pay را برای MIT تکمیل کرد برگردانده شد. این فیلدی در پایه‌بار رمزگذاری‌شده است که در شیء Card شیء.
cardUpdateInfo CardUpdateInfo الزامی حاوی به‌روزرسانی‌های مربوط به توکن است.

CardUpdateInfo

دارایی نوع ضرورت شرح
fpanSuffix رشته شرطی

شرحی برای کمک به کاربران برای شناسایی «شماره حساب اصلی تأمین وجه» (FPAN) مربوطه. رشته‌ای چهار رقمی است که حاوی چهار نویسه آخر FPAN است.

وقتی این فیلد وجود داشته باشد، می‌توان فرض کرد که وضعیت کد فعال است.

اگر تغییری وجود نداشته باشد، این دکمه نمایش داده نمی‌شود.
tokenState رشته(شمارشی) شرطی

وضعیت جدید توکن، اگر از زمان تراکنش اولیه یا اعلان قبلی تغییر کرده باشد.

اگر تغییری وجود نداشته باشد، این دکمه نمایش داده نمی‌شود.

مقدار معتبر DISABLED است.

MerchantTokenUpdateNotificationResponse

کدهای پاسخ HTTP

کد پاسخ HTTP کاربرد
۲۰۰ اعلان باموفقیت دریافت شد. اطلاعات وضعیت بیشتر می‌تواند در بدنه پاسخ به‌عنوان شیء JSON ارائه شود، همان‌گونه که در جدول بعدی شرح داده می‌شود.
401 targetNotificationUrl در MerchantTokenUpdateNotificationRequest نامعتبر است. همه اعلان‌های آینده برای این کد را می‌توان غیرفعال کرد.
‫5xx خطای موقت سرور. اعلان باید در فرصت دیگری دوباره ارسال شود.
غیره خطای غیرقابل‌تکرار. اعلان نباید بعداً دوباره ارسال شود.
دارایی نوع ضرورت شرح
requestMessageId رشته الزامی

شناسه پیام تولیدشده از درخواست.

باید با شناسه پیام از درخواست مطابقت داشته باشد، درغیراین‌صورت پاسخ می‌تواند نادیده گرفته شود و اعلان‌های آینده برای این کد متوقف می‌شود.
status رشته(شمارشی) الزامی

فروشنده یا «ارائه‌دهنده سرویس پرداخت» (PSP) می‌تواند وضعیتی را برگرداند که نشان‌دهنده دریافت اعلان و استفاده آن‌ها از این توکن باشد.

مقادیر معتبر عبارت‌اند از:

  • SUCCESS
  • TOKEN_NOT_IN_USE
  • TOKEN_NOT_FOUND

مثال

اعلان چرخه حیات

درخواست اعلان

این درخواست HTTP POST است که حاوی اعلان LCM توکن است و از Google Pay به نقطه پایانی شما ارسال می‌شود. بدنه یک بار داده رمزگذاری‌شده است.

درخواست 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"
    }
  }

پاسخ اعلان

  HTTP 200 OK
  Content-Type: application/json

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

با نقطه پایان tokenUpdateUrl خودتان آزمایش کنید

در حالت «آزمایشی»، Google Pay اعلان LCM کد به tokenUpdateUrl شما ارسال می‌کند. برای راه‌اندازی این ویژگی، این مراحل را دنبال کنید:

  • تراکنش آزمایشی را با فراخوانی loadPaymentData با شیء *TransactionInfo و پر کردن فیلد tokenUpdateUrl با نشانی وب نقطه پایانی‌تان تکمیل کنید.
  • سرویس Google اعلان LCM توکن را به نقطه پایانی شما ارسال خواهد کرد.
  • تأیید کنید که می‌توانید اعلان را بااستفاده از کلید خصوصی‌تان رمزگشایی کنید. توجه داشته باشید که در حالت «آزمایشی»، این اعلان همیشه ۴ رقم آخر شماره کارت را به «۱۲۳۴» تغییر می‌دهد و حاوی "tokenState": "DISABLED" خواهد بود، صرف‌نظر از اینکه چه نشانه‌ای در درخواست باشد.