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

نمای کلی

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

درخواست اعلان به‌روزرسانی توکن فروشنده

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

ملک	نوع	ضرورت	توضیحات
messageId	رشته	مورد نیاز	شناسه منحصر به فرد این اعلان برای حذف پیام‌های تکراری و اشکال‌زدایی. اگر این اعلان با موفقیت ارسال نشود، برای تلاش‌های بعدی به همین شکل باقی می‌ماند.
targetNotificationUrl	رشته	مورد نیاز	آدرس اینترنتی (URL) مورد نظر برای این اعلان. شما باید تأیید کنید که این آدرس اینترنتی، نقطه پایانی مورد نظر شما برای دریافت اعلان‌های LCM توکن از Google Pay است. توجه: اگر نشانی اینترنتی متعلق به شما نیست یا نادرست است، باید با HTTP 400 پاسخ دهید.
timestamp	رشته	مورد نیاز	مهر زمانی که این اعلان در ابتدا ایجاد شده است. این مهر برای تلاش‌های مجدد بعدی ثابت می‌ماند. اگر چندین اعلان برای یک شناسه توکن یکسان دریافت کنید، فقط اعلانی که آخرین برچسب زمانی را دارد، دقیق در نظر گرفته می‌شود.
apiVersion	عدد صحیح	مورد نیاز	نسخه اصلی API.
apiVersionMinor	عدد صحیح	مورد نیاز	نسخه فرعی API.
merchantTokenId	رشته	مورد نیاز	شناسه توکن فروشنده به همراه به‌روزرسانی. این شناسه‌ای است که در ابتدا هنگام تکمیل جریان Google Pay برای MIT توسط کاربر بازگردانده شده است. این فیلدی در payload رمزگذاری شده است که در شیء Card .
cardUpdateInfo	اطلاعات به‌روزرسانی کارت	مورد نیاز	شامل به‌روزرسانی‌هایی برای توکن است.

اطلاعات به‌روزرسانی کارت

ملک	نوع	ضرورت	توضیحات
fpanSuffix	رشته	مشروط	توضیحی برای کمک به کاربران در شناسایی شماره حساب اصلی تأمین مالی (FPAN). این شماره یک رشته چهار رقمی است که شامل چهار کاراکتر آخر FPAN می‌شود. وقتی وجود داشته باشد، می‌توان فرض کرد که وضعیت توکن فعال است. اگر تغییری نباشد، وجود ندارد.
tokenState	رشته (شمارشی)	مشروط	وضعیت جدید توکن، در صورت تغییر از زمان تراکنش اولیه یا اطلاع‌رسانی قبلی. اگر تغییری نباشد، وجود ندارد. مقدار معتبر DISABLED است.

پاسخ اعلان به‌روزرسانی توکن فروشنده

کدهای پاسخ HTTP

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

ملک	نوع	ضرورت	توضیحات
requestMessageId	رشته	مورد نیاز	شناسه پیام تولید شده از درخواست. باید با شناسه پیام از درخواست مطابقت داشته باشد، در غیر این صورت پاسخ می‌تواند نادیده گرفته شود و اعلان‌های آینده برای این توکن متوقف می‌شوند.
status	رشته (شمارشی)	مورد نیاز	فروشنده یا ارائه‌دهنده خدمات پرداخت (PSP) می‌تواند وضعیتی را برگرداند که نشان‌دهنده دریافت اعلان و استفاده آنها از توکن باشد. مقادیر معتبر عبارتند از: SUCCESS TOKEN_NOT_IN_USE TOKEN_NOT_FOUND

مثال

اعلان چرخه عمر

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

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

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

در حالت تست، گوگل پی یک اعلان LCM توکن به tokenUpdateUrl شما ارسال می‌کند. برای فعال کردن این حالت، این مراحل را دنبال کنید:

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