התראות על ניהול מחזור החיים של טוקנים

סקירה כללית

הודעות עתידיות על ניהול מחזור החיים (LCM) של טוקנים נשלחות מ-Google Pay Online API אל tokenUpdateUrl שצוין בזמן העסקה המקורית. הן נשלחות אם אסימון מושבת או נמחק. הם נשלחים גם על בסיס המאמץ המרבי, עם ניסיונות חוזרים למסירות שנכשלו. דוגמה לתהליך LCM כשמשתמש מסיר כרטיס מ-Google Wallet:

MerchantTokenUpdateNotificationRequest

הודעת HTTP POST מ-Google Pay Online API מכילה גוף JSON שמכיל מטען ייעודי מוצפן. המטען הייעודי מוצפן באמצעות מפתח ההצפנה הציבורי המשותף שלכם, ונחתם באמצעות המפתח הפרטי של Google. אפשר לפענח באמצעות מפתח ההצפנה הפרטי ולאמת באמצעות מפתח החתימה הבסיסי של Google. הפורמט של העטיפה הזו של מטען ייעודי מוצפן זהה לפורמט שאולי תקבלו בתור PaymentMethodToken. אפשר להשתמש באותה ספרייה כדי לפענח את ההתראה הזו על LCM. בתוך מטען הייעודי המוצפן, יש אובייקט MerchantTokenUpdateNotificationRequest כפי שמפורט כאן.

נכס סוג הכרחיות תיאור
messageId מחרוזת חובה

מזהה ייחודי של ההתראה הזו, שמשמש להסרת כפילויות מההודעות ולמטרות ניפוי באגים.

אם ההתראה הזו לא נמסרת בהצלחה, היא נשארת ללא שינוי בניסיונות חוזרים בעתיד.
targetNotificationUrl מחרוזת חובה

כתובת ה-URL שאליה ההתראה הזו מתייחסת. עליך לאשר שכתובת ה-URL הזו היא נקודת הקצה שבה אתה רוצה לקבל מ-Google Pay התראות על מחזור החיים של הטוקן.
timestamp מחרוזת חובה

חותמת הזמן של מועד היצירה המקורי של ההתראה הזו. ההגדרה הזו נשארת קבועה גם אם מנסים שוב בעתיד.

אם קיבלתם כמה התראות לאותו מזהה אסימון, רק ההתראה עם חותמת הזמן האחרונה נחשבת מדויקת.
apiVersion int חובה הגרסה הראשית של ה-API.
apiVersionMinor int חובה גרסה משנית של ה-API.
merchantTokenId מחרוזת חובה מזהה הטוקן של המוכר עם עדכון. זה המזהה שמוחזר במקור כשהמשתמש משלים את התהליך של Google Pay לקבלת הרשאה לשימוש בפרטי אמצעי התשלום. זהו שדה במטען הייעודי (payload) המוצפן, שנשלח באובייקט Card אובייקט.
cardUpdateInfo CardUpdateInfo חובה מכיל עדכונים לטוקן.

CardUpdateInfo

נכס סוג הכרחיות תיאור
fpanSuffix מחרוזת משפטי תנאי

תיאור שיעזור למשתמשים לזהות את מספר הכרטיס המקורי (FPAN) הבסיסי. זהו מחרוזת של ארבע ספרות שמכילה את ארבעת התווים האחרונים של ה-FPAN.

אם הוא קיים, אפשר להניח שהסטטוס של הטוקן הוא פעיל.

הוא לא מופיע אם לא חל שינוי.
tokenState מחרוזת(enum) משפטי תנאי

המצב החדש של האסימון, אם הוא השתנה מאז העסקה הראשונית או ההודעה הקודמת.

הוא לא מופיע אם לא חל שינוי.

הערך החוקי הוא DISABLED.

MerchantTokenUpdateNotificationResponse

קודי תגובה של HTTP

קוד תגובת HTTP שימוש
200 ההתראה מתקבלת. אפשר לספק מידע נוסף על הסטטוס בגוף התגובה כאובייקט JSON, כפי שמתואר בטבלה הבאה.
401 הערך targetNotificationUrl ב-MerchantTokenUpdateNotificationRequest לא תקין. אפשר להשבית את כל ההתראות העתידיות לטוקן הזה.
5xx שגיאת שרת זמנית. צריך לשלוח את ההתראה שוב מאוחר יותר.
אחר שגיאה שלא ניתן לנסות שוב. ההתראה לא אמורה להישלח שוב בשלב מאוחר יותר.
נכס סוג הכרחיות תיאור
requestMessageId מחרוזת חובה

מזהה ההודעה שנוצר מהבקשה.

הערך צריך להיות זהה למזהה ההודעה מהבקשה, אחרת אפשר להתעלם מהתגובה ולהפסיק את ההתראות העתידיות לגבי הטוקן הזה.
status מחרוזת(enum) חובה

המוֹכר או ספק שירותי התשלום (PSP) יכולים להחזיר סטטוס שמשקף את הקליטה של ההתראה ואת השימוש באסימון.

הערכים החוקיים כוללים:

  • SUCCESS
  • TOKEN_NOT_IN_USE
  • TOKEN_NOT_FOUND

דוגמה

התראה על מחזור חיים

בקשת התראה

זוהי בקשת HTTP POST שמכילה את ההתראה על מחזור החיים של הטוקן, שנשלחת מ-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 שולחת התראה על מחזור החיים של הטוקן אל tokenUpdateUrl. כדי להפעיל את התהליך הזה, מבצעים את השלבים הבאים:

  • כדי להשלים עסקת בדיקה, קוראים ל-loadPaymentData עם אובייקט *TransactionInfo ומאכלסים את השדה tokenUpdateUrl עם כתובת ה-URL של נקודת הקצה.
  • השירות של Google ישלח התראה על מחזור החיים של הטוקן לנקודת הקצה שלכם.
  • מוודאים שאפשר לפענח את ההתראה באמצעות המפתח הפרטי. הערה: במצב בדיקה, ההתראה הזו תמיד תשנה את 4 הספרות האחרונות של מספר הכרטיס ל-1234 ותכיל את "tokenState": "DISABLED", ללא קשר לטוקן שבבקשה.