إشعارات إدارة مراحل نشاط الرموز المميّزة

نظرة عامة

يتم إرسال إشعارات إدارة دورة حياة الرمز المميّز (LCM) المستقبلية من واجهة برمجة التطبيقات Google Pay Online إلى عنوان البريد الإلكتروني tokenUpdateUrl المقدَّم في وقت المعاملة الأصلية. يتم إرسالها في حال إيقاف رمز مميّز أو حذفه. ويتم أيضًا بذل أقصى مجهود في هذا الإطار مع إعادة المحاولة في حال تعذّر التسليم. في ما يلي مثال على مسار LCM عند إزالة بطاقة من "محفظة Google" من قِبل المستخدم:

MerchantTokenUpdateNotificationRequest

تحمل رسالة HTTP POST من Google Pay Online API نص JSON يغلف حمولة مشفّرة. يتم تشفير الحمولة باستخدام مفتاح التشفير العام المشترَك، ويتم توقيعها باستخدام المفتاح الخاص من Google. يمكنك فك التشفير باستخدام مفتاح التشفير الخاص، وإثبات صحة التوقيع باستخدام مفتاح التوقيع الأساسي من Google. تنسيق غلاف الحمولة المشفّرة هذا مطابق لما قد تتلقّاه كـ PaymentMethodToken. يمكنك استخدام المكتبة نفسها لفك تشفير إشعار LCM هذا. ضمن الحمولة المشفّرة، هناك عنصر MerchantTokenUpdateNotificationRequest كما هو موضّح بالتفصيل هنا.

الموقع النوع الضرورة الوصف
messageId سلسلة مطلوب

المعرّف الفريد لهذا الإشعار لإزالة التكرار من الرسائل ولأغراض تصحيح الأخطاء

إذا لم يتم تسليم هذا الإشعار بنجاح، سيظل كما هو في محاولات إعادة الإرسال المستقبلية.
targetNotificationUrl سلسلة مطلوب

عنوان URL المقصود لهذا الإشعار. يجب تأكيد أنّ عنوان URL هذا هو نقطة النهاية المقصودة لتلقّي إشعارات إدارة دورة حياة الرمز المميّز من Google Pay.
timestamp سلسلة مطلوب

الطابع الزمني لوقت إنشاء هذا الإشعار في الأصل ويظلّ كما هو في المحاولات المستقبلية.

إذا تلقّيت إشعارات متعدّدة لمعرّف الرمز المميز نفسه، سيتم اعتبار الإشعار الذي يتضمّن أحدث طابع زمني هو الإشعار الدقيق.
apiVersion int مطلوب رقم الإصدار الرئيسي لواجهة برمجة التطبيقات
apiVersionMinor int مطلوب رقم الإصدار الثانوي لواجهة برمجة التطبيقات
merchantTokenId سلسلة مطلوب معرّف الرمز المميّز للتاجر مع تعديل هذا هو رقم التعريف الذي تم عرضه في الأصل عندما أكمل المستخدم تدفق Google Pay الخاص بالدفع المتكرّر. هذا حقل ضمن الحمولة المشفّرة، يتم إرساله في الكائن Card.
cardUpdateInfo CardUpdateInfo مطلوب يحتوي على تحديثات للرمز المميّز.

CardUpdateInfo

الموقع النوع الضرورة الوصف
fpanSuffix سلسلة الجملة الشرطية

وصف لمساعدة المستخدمين في تحديد رقم الحساب الأساسي للتمويل (FPAN) الأساسي وهي سلسلة من أربعة أرقام تحتوي على آخر أربعة أحرف من FPAN.

عند توفّره، يمكن افتراض أنّ حالة الرمز المميّز نشطة.

لا يظهر هذا الحقل إذا لم يتم إجراء أي تغيير.
tokenState سلسلة(تعداد) الجملة الشرطية

الحالة الجديدة للرمز المميّز، إذا تم تغييره منذ المعاملة الأولية أو الإشعار السابق

لا يظهر هذا الحقل إذا لم يتم إجراء أي تغيير.

القيمة الصالحة هي DISABLED.

MerchantTokenUpdateNotificationResponse

رموز استجابة HTTP

رمز استجابة HTTP الاستخدام
200 تم تلقّي الإشعار بنجاح. يمكن تقديم معلومات إضافية عن الحالة في نص الردّ كعنصر 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 إشعارًا بشأن إدارة دورة حياة الرمز المميز إلى جهاز tokenUpdateUrl. لتفعيل هذه الميزة، اتّبِع الخطوات التالية:

  • أكمِل معاملة تجريبية عن طريق استدعاء loadPaymentData باستخدام كائن *TransactionInfo، مع ملء الحقل tokenUpdateUrl بعنوان URL الخاص بنقطة النهاية.
  • سترسل خدمة Google إشعارًا مميزًا بشأن إدارة مراحل النشاط إلى نقطة النهاية.
  • تأكَّد من إمكانية فك تشفير الإشعار باستخدام مفتاحك الخاص. يُرجى العِلم أنّه في وضع الاختبار، سيؤدي هذا الإشعار دائمًا إلى تغيير آخر 4 أرقام من رقم البطاقة إلى "1234" وسيتضمّن "tokenState": "DISABLED"، بغض النظر عن الرمز المميّز في الطلب.