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

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

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

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

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

نقدًا

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

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

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

VAN

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

يجب أن تتأكّد الشركة المتعهّدة من أنّ المبلغ الذي تم نقله يتطابق مع مبلغ طلب referenceNumber Generation، ثم إعلام 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 أرقام تعريف حسابات تكامل الدفعات (PIAIDs). للحصول على مثال على واجهة برمجة تطبيقات FOP النقدية، راجع generateReferenceNumber. إليك نموذج يستخدم هذا التعيين.

لعمليات الربط من كلّ كيان على Google وكلّ حساب تاجر، تقدّم Google أرقام تعريف حسابات تكامل الدفعات (PIAIDs). للحصول على مثال حول استخدام واجهة برمجة تطبيقات الدفع النقدي، يُرجى مراجعة 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"
}

نموذج جافا

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

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

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

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

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

عنوان 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 لهذا الإشعار، تتوقّع أن تكون المعاملة نهائية ولا يمكن حجزها.

عنوان 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"
}