راهنمای Cash FOP (AKA Reference Number API).

در اینجا چند مورد استفاده مهم و همچنین دستورالعمل ها و API های مورد نیاز برای اجرای FOP نقدی شما وجود دارد.

موارد استفاده کنید

تعدادی کاربرد برای Reference Number API وجود دارد. این راهنما دو مورد استفاده را مورد بحث قرار می دهد و شما را در اجرای آنها راهنمایی می کند.

  • نقدی - کاربر به صورت نقدی در یک مکان فیزیکی پرداخت می کند.
  • VAN - کاربر پول را به شماره حساب مجازی منتقل می کند.

پول نقد

کاربر می تواند با پرداخت پول نقد در یک مکان فیزیکی، مانند یک فروشگاه رفاه، چیزی از Google بخرد. برای شناسایی تراکنش، کاربر یک شماره مرجع ایجاد می کند تا برای پرداخت به فروشگاه ببرد. علاوه بر این، گوگل دستورالعمل هایی را در مورد نحوه تکمیل خرید به کاربر نمایش می دهد. در حالت ایده‌آل، به محض اینکه کاربر خرید را کامل کرد، ادغام‌کننده به Google اطلاع می‌دهد تا Google بتواند محصول را تحویل دهد.

محل تماس شما در Google نمونه ای از دستورالعمل های پرداخت معمولی شما را می خواهد. برای بهینه‌سازی و اصلاح پیام‌ها با مخاطب Google خود کار خواهید کرد.

تجربه کاربری که Google می‌خواهد ارائه کند این است که سفارش مشتری هنگام خروج از فروشگاه تحویل داده می‌شود. Google انتظار دارد ReferenceNumberPaidNotification ظرف سه دقیقه پس از پرداخت شماره مرجع توسط مشتری در Google دریافت شود. هنگامی که ReferenceNumberPaidNotification ارسال شد، تراکنش نمی تواند توسط یکپارچه کننده معکوس شود.

VAN

کاربر می تواند برای کالایی با حساب بانکی خود پرداخت کند. Google با ارائه شماره و دستورالعمل‌ها به کاربر، یک شماره حساب مجازی از ادغام‌کننده درخواست می‌کند. سپس کاربر شماره را کپی کرده و علاوه بر مبلغ انتقال، در برنامه بانکی خود وارد می کند.

یکپارچه‌کننده باید تأیید کند که مبلغ انتقال‌یافته با مقدار درخواست referenceNumberGeneration مطابقت دارد، سپس به Google اطلاع دهد که شماره مرجع پرداخت شده است.

وقتی Google ReferenceNumberPaidNotification را دریافت کرد، Google محصول را تحویل می‌دهد و ادغام‌کننده نمی‌تواند تراکنش را برگرداند.

Sending messages between your servers and Google's servers

When sending messages between your servers and Google’s servers, or the other way around, please do so according to these guidelines.

Incoming request - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

Outgoing response - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google request - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google response - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

Here is a PGP library and sample in java that shows handling requests and responses.

از رفتار ناتوان پیروی کنید

عدم توانایی به این معنی است که شما نباید تلاش کنید تا درخواستی (مانند پرداخت) که قبلاً با موفقیت پردازش شده است را مجدداً پردازش کنید. پاسخ برای پردازش موفقیت آمیز باید به جای آن گزارش شود.

چرا مهم است

ممکن است Google برخی از درخواست‌ها را دوباره امتحان کند تا مطمئن شود وضعیت طرف ما با وضعیت طرف فروشنده یکسان است. سیستم شما نباید فکر کند که این یک معامله دیگر است. بنابراین، ناتوانی بسیار مهم است. این بدان معنی است که یک ادغام کننده نباید چیزی را که قبلاً با موفقیت پردازش شده است، دوباره پردازش کند. در چنین حالتی، پاسخ قبلی باید به جای آن ارسال شود.

نحوه پیاده سازی بی قدرتی

اگر Google یک امتحان مجدد ارسال کند، شناسه درخواست یکسان خواهد بود و محتوا یکسان است، اما مهر زمانی متفاوت خواهد بود. با همان پاسخی که قبلا فرستاده اید پاسخ دهید. اگر اولین پاسخ شما 200 (موفقیت) بود، گوگل همان پاسخ را با مهر زمانی متفاوت انتظار داشت.

اگر پاسخ قبلی شما یک خطا بود (400 یا 500 و غیره)، پس باید آن درخواست را به عنوان یک درخواست جدید پردازش کنید و دوباره آن را بررسی کنید. اگر سرور شما اولین بار از کار افتاده باشد و امتحان مجدد آن فرصت دیگری برای پردازش موفقیت آمیز درخواست می دهد، مفید است.

برای کسب اطلاعات بیشتر، این راهنمای دقیق را ببینید.

از شناسه حساب یکپارچه کننده پرداخت (PIAID) استفاده کنید

ادغام با Google ممکن است نیاز به ادغام با نهادهای تجاری مختلف Google داشته باشد. به عنوان مثال، Google Play یک نهاد است، دیگری یوتیوب، و دیگری Google Ads است. اینها شامل حساب‌های تجاری مختلف برای نمایش هر یک از این پیکربندی‌ها می‌شوند.

برای نگاشت هر نهاد در Google به هر حساب تاجر، Google شناسه‌های حساب یکپارچه‌کننده پرداخت (PIAID) را ارائه می‌کند. برای مثال برای Cash FOP API، به generateReferenceNumber مراجعه کنید. در اینجا نمونه ای است که از این نقشه برداری استفاده می کند.

برای نگاشت هر نهاد در Google به هر حساب تاجر، Google شناسه‌های حساب یکپارچه‌کننده پرداخت (PIAID) را ارائه می‌کند. برای مثال با استفاده از Cash FOP API، به 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 دیگری برای هر کشور ایجاد شود.

API برای ادغام

APIهای زیر تولید شماره مرجع و اعلان پرداخت را مدیریت می کنند.

APIهای زیر حواله و تسویه حساب را مدیریت می کنند.

برای ایجاد شماره های مرجع و تسویه حساب با Google، باید همه API های فوق را ادغام کنید.

شماره مرجع ایجاد کنید

هنگامی که شما خریدی را شروع می کنید، 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_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"
}

حواله را اجرا کنید

هنگامی که API ها را برای FOP خاص خود ادغام کردید، برای حواله آماده هستید. حواله در تمام FOPها یکسان عمل می کند.

remittanceStatementNotification

دو روز پس از تراکنش، Google حواله‌ای را ارسال می‌کند که حاوی خلاصه‌ای از تراکنش‌هایی است که 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"
}