ক্যাশ এফওপি (একেএ রেফারেন্স নম্বর API) গাইড

এখানে কিছু গুরুত্বপূর্ণ ব্যবহারের ক্ষেত্রে বিবেচনা করা হয়েছে, সেইসাথে আপনার নগদ FOP বাস্তবায়নের জন্য প্রয়োজনীয় নির্দেশিকা এবং API।

কেস ব্যবহার করুন

রেফারেন্স নম্বর API-এর জন্য অনেকগুলি ব্যবহার রয়েছে। এই নির্দেশিকা দুটি ব্যবহারের ক্ষেত্রে আলোচনা করবে এবং তাদের বাস্তবায়নের মাধ্যমে আপনাকে নিয়ে যাবে।

  • নগদ - ব্যবহারকারী একটি শারীরিক অবস্থানে নগদ অর্থ প্রদান করে।
  • VAN - ব্যবহারকারী একটি ভার্চুয়াল অ্যাকাউন্ট নম্বরে অর্থ স্থানান্তর করে।

নগদ

একজন ব্যবহারকারী Google থেকে কিছু কিনতে পারেন নগদ অর্থ দিয়ে একটি বাস্তব অবস্থানে, যেমন একটি সুবিধার দোকানে। লেনদেন শনাক্ত করতে, ব্যবহারকারী দোকানে অর্থ প্রদানের জন্য একটি রেফারেন্স নম্বর তৈরি করবে। উপরন্তু, কিভাবে ক্রয় সম্পূর্ণ করতে হবে সে সম্পর্কে Google ব্যবহারকারীকে নির্দেশাবলী প্রদর্শন করবে। আদর্শভাবে ব্যবহারকারী কেনাকাটা সম্পূর্ণ করার সাথে সাথে, ইন্টিগ্রেটর Google কে অবহিত করে যাতে Google পণ্যটি সরবরাহ করতে পারে।

Google-এ আপনার যোগাযোগের স্থানটি আপনার সাধারণ অর্থপ্রদানের নির্দেশাবলীর একটি নমুনা চাইবে। আপনি মেসেজিং অপ্টিমাইজ এবং পরিমার্জিত করতে আপনার Google পরিচিতির সাথে কাজ করবেন৷

Google যে ব্যবহারকারীর অভিজ্ঞতা প্রদান করতে চায় তা হল গ্রাহকের অর্ডার বিতরণ করা হয় যখন তারা দোকান ছেড়ে যাচ্ছে। Google আশা করে যে গ্রাহক রেফারেন্স নম্বর প্রদান করার তিন মিনিটের মধ্যে Google-এ ReferenceNumberPaidNotification পেয়ে যাবে। একবার ReferenceNumberPaidNotification পাঠানো হলে, ইন্টিগ্রেটর দ্বারা লেনদেনটি ফেরানো যাবে না।

ভ্যান

একজন ব্যবহারকারী তাদের ব্যাঙ্ক অ্যাকাউন্ট দিয়ে ভালো কিছুর জন্য অর্থ প্রদান করতে পারেন। Google ইন্টিগ্রেটরের কাছ থেকে একটি ভার্চুয়াল অ্যাকাউন্ট নম্বর অনুরোধ করবে, ব্যবহারকারীর কাছে নম্বর এবং নির্দেশাবলী উপস্থাপন করবে। ব্যবহারকারী তারপর নম্বরটি অনুলিপি করবে এবং স্থানান্তর করার পরিমাণ ছাড়াও এটি তাদের ব্যাঙ্কিং অ্যাপ্লিকেশনে প্রবেশ করবে।

ইন্টিগ্রেটরকে যাচাই করতে হবে যে স্থানান্তরিত পরিমাণ রেফারেন্স নম্বর জেনারেশন অনুরোধের পরিমাণের সাথে মেলে, তারপর 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 কিছু অনুরোধের জন্য আবার চেষ্টা করতে পারে। আপনার সিস্টেম মনে করা উচিত নয় যে এটি অন্য লেনদেন। অতএব, বুদ্ধিমত্তা খুবই গুরুত্বপূর্ণ। এর অর্থ হল একটি ইন্টিগ্রেটরকে এমন কিছু পুনঃপ্রক্রিয়া করা উচিত নয় যা ইতিমধ্যে সফলভাবে প্রক্রিয়া করা হয়েছে। এই ধরনের ক্ষেত্রে, পূর্ববর্তী প্রতিক্রিয়া পরিবর্তে পাঠানো উচিত।

কিভাবে Idempotency বাস্তবায়ন করতে হয়

যদি Google পুনরায় চেষ্টা করে, তাহলে অনুরোধ আইডি একই হবে এবং বিষয়বস্তু একই হবে, কিন্তু টাইমস্ট্যাম্প ভিন্ন হবে। আপনি পূর্বে যে প্রতিক্রিয়া পাঠিয়েছেন সেই একই প্রতিক্রিয়া দিয়ে উত্তর দিন। যদি আপনার প্রথম প্রতিক্রিয়া 200 (সফল) হয়, তাহলে Google একটি ভিন্ন টাইমস্ট্যাম্প সহ একই প্রতিক্রিয়া আশা করবে।

যদি আপনার পূর্ববর্তী প্রতিক্রিয়া একটি ত্রুটি (400 বা 500 ইত্যাদি) হয়ে থাকে, তাহলে আপনার সেই অনুরোধটিকে একটি নতুন অনুরোধ হিসাবে প্রক্রিয়া করা উচিত, এটি আবার পরীক্ষা করা। এটি সহায়ক যদি আপনার সার্ভার প্রথমবার ডাউন হয় এবং এটি পুনরায় চেষ্টা করা অনুরোধটিকে সফলভাবে প্রক্রিয়া করার আরেকটি সুযোগ দেয়।

আরও জানতে, এই বিস্তারিত নির্দেশিকা দেখুন।

পেমেন্ট ইন্টিগ্রেটর অ্যাকাউন্ট আইডি (পিআইএআইডি) ব্যবহার করুন

Google-এর সাথে একীকরণের জন্য Google-এর বিভিন্ন ব্যবসায়িক সত্তার সাথে একীভূত হওয়ার প্রয়োজন হতে পারে। উদাহরণস্বরূপ, Google Play হল একটি সত্তা, আরেকটি হল YouTube, এবং আরেকটি হল Google Ads৷ এই কনফিগারেশনের প্রতিটি প্রতিনিধিত্ব করার জন্য এটি বিভিন্ন বণিক অ্যাকাউন্টগুলিকে অন্তর্ভুক্ত করবে।

Google-এর প্রতিটি সত্তা থেকে প্রতিটি মার্চেন্ট অ্যাকাউন্টে ম্যাপিংয়ের জন্য, Google পেমেন্ট ইন্টিগ্রেটর অ্যাকাউন্ট আইডি (PIAIDs) প্রদান করে। নগদ FOP API-এর উদাহরণের জন্য, generateReferenceNumber দেখুন। এখানে একটি নমুনা যা এই ম্যাপিং ব্যবহার করে।

Google-এর প্রতিটি সত্তা থেকে প্রতিটি মার্চেন্ট অ্যাকাউন্টে ম্যাপিংয়ের জন্য, Google পেমেন্ট ইন্টিগ্রেটর অ্যাকাউন্ট আইডি (PIAIDs) প্রদান করে। নগদ 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"
}

হাইলাইট করা অংশটি লক্ষ্য করুন। এখানে যে দুটি মান প্রয়োজন তা হল Google-এ আপনার যোগাযোগের পয়েন্ট এবং আপনার বণিক অ্যাকাউন্ট দ্বারা প্রদত্ত paymentIntegratorAccountId ।

পরিসেবা করা প্রতিটি দেশ অনুযায়ী ইন্টিগ্রেটরের আলাদা অ্যাকাউন্ট থাকতে পারে। এটি বিভিন্ন ট্যাক্স আইন এবং এক দেশ থেকে অন্য দেশে অন্যান্য পার্থক্যের কারণে হতে পারে। এই ক্ষেত্রে প্রতিটি দেশের জন্য আরেকটি PIAID তৈরি করা হতে পারে।

এপিআই একত্রিত করতে

নিম্নলিখিত 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 প্রতিক্রিয়া এবং 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 আশা করে যে লেনদেন চূড়ান্ত হয়ে গেছে এবং সংরক্ষণযোগ্য নয়।

referenceNumberPaidNotification endpoint URL:


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"
}

Implement remittance

Once you have integrated the APIs for your particular FOP, you are ready for remittance. Remittance works the same across all FOPs.

remittanceStatementNotification

Two days after a transaction, Google will send a remittanceStatementNotification containing a summary of the transactions Google recorded that day. A sample notification looks like this, two days after a transaction:

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

Request 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",
  }
}

Notice the totalDueByIntegrator mapping. On this line you can see the net amount the Integrator owes (in micros). Also, the date and type of currency appear in this message, with the billing period representing 00:00:00.000 and 23:59:59.999 of the earliest and latest transaction day(s) respectively.

Reconciliation (remittanceStatementDetails)

For reconciliation, the integrator will call remittanceStatementDetails to get the list of events included in the remittanceStatementNotification.

Google responds to the remittanceStatementDetails request with a paginated list of events. remittanceStatementDetails should be called multiple times if the number of total transactions is greater than 1000. The requests do not need to be made sequentially, and can be parallelized.

Request URL

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

Sample request body

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

Here is a short snippet of a larger response, describing two capture events (transactions).

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

See remittanceStatementDetails to learn more.

acceptRemittanceStatement and acceptRemittanceStatementWithModifications

Integrators should compare these events against the events that they have recorded. If any transactions do not match or transactions are missing, contact Google for further investigation. If all transactions match, and the process fee does not include taxes, call acceptRemittanceStatement. If taxes are inclusive, call acceptRemittanceStatementWithModifications.

The acceptRemittanceStatement method is used when there are no taxes on fees.

If a tax is to be included, call acceptRemittanceStatementWithModifications and define the tax rate. If your tax rate changes, make sure this is updated. After a successful acceptRemittanceStatement, initiate your bank transfer to the Google account.

Request URL for acceptRemittanceStatement

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

Sample request body

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

Sample response

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

Request URL for acceptRemittanceStatementWithModifications

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

Sample request body

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

Sample response

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