دليل واجهة برمجة التطبيقات للرقم المرجعي للنقود (FOP)

في ما يلي بعض حالات الاستخدام المهمة التي يجب مراعاتها، بالإضافة إلى الإرشادات وواجهات برمجة التطبيقات اللازمة لتطبيق طريقة الدفع النقدي الخاصة بك.

حالات الاستخدام

هناك عدد من استخدامات واجهة برمجة التطبيقات Reference Number API. سيناقش هذا الدليل حالتَي استخدام وسيرشدك إلى كيفية تنفيذهما.

  • نقدًا - يدفع المستخدم نقدًا في موقع جغرافي.
  • VAN - يحوِّل المستخدم الأموال إلى رقم حساب افتراضي.

نقدًا

يمكن للمستخدم شراء سلعة من Google عن طريق دفعها نقدًا في موقع جغرافي، مثل متجر صغير. لتحديد المعاملة، سينشئ المستخدم رقمًا مرجعيًا يأخذه إلى المتجر للدفع. بالإضافة إلى ذلك، ستعرض Google تعليمات للمستخدم حول كيفية إكمال عملية الشراء. ومن المفترَض أن ترسل شركة الدمج إشعارًا إلى Google لتتمكّن Google من تسليم المنتج فور انتهاء المستخدم من عملية الشراء.

ستطلب جهة التواصل المعيّنة من جانبك في Google تقديم عيّنة من تعليمات الدفع المعتادة. ويمكنك العمل مع جهة اتصال Google التي تتعامل معها لتحسين عملية المراسلة.

إنّ تجربة المستخدم التي تريد Google تقديمها هي أنّ طلب العميل يتم تسليمه أثناء مغادرته للمتجر. وتتوقّع Google تلقّي ReferenceNumberPaidNotification على Google في غضون ثلاث دقائق من دفع العميل للرقم المرجعي. وبعد إرسال ReferenceNumberpaidNotification، لا يمكن لشركة الدمج التراجع عن المعاملة.

رقم الحساب الافتراضي

يمكن للمستخدم دفع ثمن سلعة باستخدام حسابه المصرفي. ستطلب Google من شركة الدمج توفير رقم حساب افتراضي يتضمّن الرقم والتعليمات الخاصة به. على المستخدم بعد ذلك نسخ الرقم وإدخاله في تطبيقه المصرفي بالإضافة إلى المبلغ المطلوب تحويله.

وعلى شركة الدمج التحقّق من أنّ المبلغ المنقول يتطابق مع مبلغ الطلب assetNumberGeneration، ثم إعلام Google بأنّه تم دفع الرقم المرجعي.

وبعد أن تتلقّى Google الإشعار ReferenceNumberPaidNotification، تسلم Google المنتج ولا يمكن لشركة الدمج التراجع عن المعاملة.

إرسال الرسائل بين خوادمك وخوادم Google

وعند إرسال رسائل بين خوادمك وخوادم Google، أو العكس، يُرجى إجراء ذلك وفقًا لهذه الإرشادات.

طلب وارد - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

الرد الصادر - Base64UrlEncode(EncryptWithGooglePublicKey(request))

طلب من Google - Base64UrlEncode(EncryptWithGooglePublicKey(request))

رد Google - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

في ما يلي مكتبة لـ PGP ونموذج في جافا يوضّحان التعامل مع الطلبات والردود.

اتّباع السلوك غير الثابت

تعني حالة الهوية أنّه يجب عدم محاولة إعادة معالجة أي طلب (مثل الدفع) تمت معالجته بنجاح. يجب الإبلاغ عن الاستجابة للمعالجة الناجحة بدلاً من ذلك.

ما الذي يميّز هذه النسخة؟

قد تعيد Google محاولة إجراء بعض الطلبات للتأكّد من أنّ الحالة من جانبنا هي نفسها الحالة لدى المورّد. يجب ألا يعتقد النظام أنّ هذه معاملة أخرى. لذلك، تعد الهويات مهمة جدًا. ويعني ذلك أنّ جهة الدمج يجب ألّا تعيد معالجة أيّ محتوى سبق أن تمّت معالجته بنجاح. في هذه الحالة، يجب إرسال الرد السابق بدلاً من ذلك.

كيفية تنفيذ تحديد الهوية

إذا أرسلت Google إعادة محاولة، سيكون رقم تعريف الطلب هو نفسه والمحتوى نفسه، لكن الطابع الزمني سيكون مختلفًا. يمكنك الردّ وتقديم الردّ نفسه الذي أرسلته سابقًا. إذا كان ردّك الأول هو 200 (تم الإجراء بنجاح)، تتوقّع Google تلقّي الرد نفسه مع طابع زمني مختلف.

إذا كان ردّك السابق خطأً (400 أو 500 وما إلى ذلك)، عليك معالجة هذا الطلب كطلب جديد والتحقّق منه مرة أخرى. يكون هذا الأمر مفيدًا إذا كان الخادم معطلاً في المرة الأولى وإعادة المحاولة ليمنح الطلب فرصة أخرى لتتم معالجته بنجاح.

لمزيد من المعلومات، اطّلِع على هذا الدليل التفصيلي.

استخدام رقم تعريف حساب جهة تكامل الدفعات (PIAID)

قد تتطلّب عمليات الدمج مع Google الدمج مع الكيانات التجارية المختلفة في Google. على سبيل المثال، يمثل Google Play كيانًا، وآخر هو YouTube، وآخر هو "إعلانات Google". وستشمل هذه الحسابات حسابات تجّار مختلفة لتمثيل كلّ من هذه الإعدادات.

لعمليات الربط من كلّ جهة داخل Google بكل حساب تاجر، توفّر Google أرقام تعريف الحسابات الخاصة بدمج عمليات الدفع (PIAID). للحصول على مثال لواجهة برمجة تطبيقات FOP النقدية، يُرجى الاطّلاع على generateReferenceNumber. في ما يلي نموذج يستخدِم عملية الربط هذه.

لعمليات الربط من كلّ جهة داخل Google بكل حساب تاجر، توفّر Google أرقام تعريف الحسابات الخاصة بدمج عمليات الدفع (PIAID). للحصول على مثال عن استخدام واجهة برمجة تطبيقات FOP النقدية، يمكنك الاطّلاع على generateReferenceNumber. في ما يلي نموذج يستخدِم عملية الربط هذه.


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "transactionDescription": "Google - Music",
  "currencyCode": "USD",
  "amount": "2000000"
}

لاحظ الجزء المميز. القيمتان المطلوبتان هنا هما paymentIntegratorAccountId الذي تقدّمه جهة التواصل التي تتعامل معها في Google، وحساب التاجر.

وقد تملك شركة الدمج أيضًا حسابات مختلفة حسب البلد الذي يتم تقديم الخدمة فيه. وقد يعود ذلك إلى قوانين ضرائب مختلفة واختلافات أخرى من بلد إلى آخر. في هذه الحالة، قد يتم إنشاء PIAID آخر لكل بلد.

واجهات برمجة التطبيقات المراد دمجها

تتعامل واجهات برمجة التطبيقات التالية مع عملية إنشاء الأرقام المرجعية وإشعار الدفع.

تتعامل واجهات برمجة التطبيقات التالية مع الحوالات المالية والتسويات.

ستحتاج إلى دمج كل واجهات برمجة التطبيقات المذكورة أعلاه لإنشاء أرقام مرجعية وتسويتها مع Google.

إنشاء رقم مرجعي

تتصل Google بـ GenerateReferenceNumber عند بدء عملية شراء. نتوقّع منك الردّ وتقديم رقم مرجعي يحدّد المعاملة أو الحساب. وقت الاستجابة المتوقع هو < 3 ثوانٍ

بالنسبة إلى المعاملات النقدية، يمكن أن يصل الرقم المرجعي إلى 12 حرفًا.

عنوان URL: POST https://[your basepath]/v1/generateReferenceNumber

طلب ملف JSON

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
    "requestTimestamp": "1561678470395"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "transactionDescription": "Google Play - Tester",
  "currencyCode": "USD",
  "amount": "10000000"
}

استجابة JSON

{
  "responseHeader": {
    "responseTimestamp": "1561678947659"
  },
  "result": "SUCCESS",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

نموذج Java

`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`

GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);

إلغاء الرقم المرجعي

قد تختار Google إلغاء الرقم المرجعي ومنع المستخدم من الدفع له. من الأمثلة على حالات الاستخدام عرض ترويجي منتهي الصلاحية. بعد الرد بنجاح على هذا الطلب، يجب عليك التأكد من عدم إمكانية دفع الرقم المرجعي.

إذا كان المستخدم قد بدأ عملية الدفع، على سبيل المثال البحث عن رقم مرجعي من نقطة البيع، من المفترض أن يستجيب الخادم بإرسال استجابة HTTP 423 واستجابة الخطأ في نص الطلب مع الحالة USER_ACTION_IN_PROGRESS.

عنوان URL: POST https://[your basepath]/v1/cancelReferenceNumber

طلب ملف JSON

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "51e00f16-36ba-4490-b228-0a670d202206",
    "requestTimestamp": "1561678947926"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

استجابة JSON

{
  "responseHeader": {
    "responseTimestamp": "1561680406459"
  },
  "result": "SUCCESS"
}

referenceNumberPaidNotification

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

عنوان URL لنقطة نهاية referenceNumberPaidNotification:


POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]

طلب ملف JSON

{
 "requestHeader": {
    "requestTimestamp": "1561748625577",
    "requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    }
  },
  "paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
  "referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
  "paymentLocation": {
    "brandName": "TestMart",
    "locationId": "1234"
  },
   "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "paymentTimestamp": "1561748625577"
}

استجابة JSON

{
  "responseHeader": {
    "responseTimestamp": "1561748642600"
  },
  "result": "SUCCESS"
}

تطبيق الحوالة المالية

بعد دمج واجهات برمجة التطبيقات لطريقة الدفع المحدّدة، تكون مستعدًا لإجراء عمليات التحويل. تعمل عمليات التحويلات المالية بالطريقة نفسها في جميع طرق الدفع المتاحة.

remittanceStatementNotification

بعد يومين من إجراء المعاملة، سترسل Google remittanceStatementNotification يحتوي على ملخص للمعاملات التي سجلتها Google في ذلك اليوم. يظهر إشعار نموذجي على النحو التالي، بعد يومين من المعاملة:

POST https://www.integratordomain.com/v1/remittanceStatementNotification

طلب JSON


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-statement-abc",
    "requestTimestamp": "1502632800000"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "remittanceStatementSummary": {
    "statementDate": "1502607600000",
    "billingPeriod": {
      "startDate": "1502434800000",
      "endDate": "1502521199000",
    },
    "dateDue": "1503212400000",
    "currencyCode": "INR",
    "totalDueByIntegrator": "1076000000",
  }
}

لاحِظ عملية الربط totalDueByIntegrator. في هذا السطر، يمكنك الاطّلاع على المبلغ الصافي الذي يدين به "المُدمِج" (بوحدة الميكرو). بالإضافة إلى ذلك، يظهر تاريخ ونوع العملة في هذه الرسالة، مع أن المدة الزمنية للفوترة هي 00:00:00.000 و23:59:59.999 من أول أيام المعاملات وأخيرها على التوالي.

المصالحة (remittanceStatementDetails)

لإجراء عملية المصالحة، سيطلب المُدمِج remittanceStatementDetails للحصول على قائمة بالأحداث المضمّنة في remittanceStatementNotification.

تستجيب Google لطلب remittanceStatementDetails بعرض قائمة أحداث مقسّمة على صفحات. يجب استدعاء remittanceStatementDetails عدة مرات إذا كان إجمالي عدد المعاملات أكبر من 1000. ولا يلزم إرسال الطلبات بشكل تسلسلي، ويمكن إرسالها بالتوازي.

طلب عنوان URL

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails

نموذج نص الطلب

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "statement_detail_request_139932019",
    "requestTimestamp": "1502551332087"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc",
  "numberOfEvents": 4
}

في ما يلي مقتطف قصير من ردّ أكبر، يصف حدثَي تسجيل (معاملتَين).

"captureEvents": [ {
    {
      "eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
      "paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
      "eventCharge": "700000000",
      "eventFee": "-28000000"
    },
    {
      "eventRequestId": "Ggghvh78200PQ3Yrpb",
      "paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
      "eventCharge": "800000000",
      "eventFee": "-32000000"
    }
  }

يُرجى الاطّلاع على remittanceStatementDetails لمعرفة المزيد من المعلومات.

acceptRemittanceStatement وacceptRemittanceStatementWithModifications

على مُدمِجي الأنظمة مقارنة هذه الأحداث بالأحداث التي سجّلوها. إذا لم تتطابق أي معاملات أو كانت هناك معاملات غير متوفّرة، يُرجى التواصل مع Google لإجراء المزيد من التحقيق. إذا تطابقت جميع المعاملات ولم تكن رسوم المعالجة تشمل الضرائب، يُرجى الاتصال على acceptRemittanceStatement. إذا كانت الضرائب شاملة، اتّصِل بالرقم acceptRemittanceStatementWithModifications.

يتم استخدام طريقة acceptRemittanceStatement عندما لا تكون هناك ضرائب على الرسوم.

إذا أردت تضمين ضريبة، عليك الاتصال بالرقم acceptRemittanceStatementWithModifications وتحديد معدّل الضريبة. في حال تغيُّر معدّل الضريبة، احرص على تعديله. بعد إكمال عملية "acceptRemittanceStatement" بنجاح، يمكنك بدء حوالتك المصرفية إلى حساب Google.

عنوان URL لطلب acceptRemittanceStatement

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement

نموذج لنص الطلب

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
}

نموذج إجابة

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementResultCode": "SUCCESS"
}

عنوان URL لطلب acceptRemittanceStatementWithModifications

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications

نموذج لنص الطلب

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
  "feeToVatModification": {
    "vatToFeeRatioInMicros": "150000"
  }
}

نموذج إجابة

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}