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

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

ব্যবহারের ক্ষেত্রে

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

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

নগদ

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

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

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

ভ্যান

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

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

Google একবার ReferenceNumberPaidNotification প্রাপ্ত করলে, Google পণ্যটি সরবরাহ করবে এবং ইন্টিগ্রেটর দ্বারা লেনদেনটি ফেরানো যাবে না।

আপনার সার্ভার এবং Google এর সার্ভারের মধ্যে বার্তা পাঠানো হচ্ছে৷

আপনার সার্ভার এবং Google এর সার্ভারের মধ্যে বার্তা পাঠানোর সময়, বা অন্যভাবে, অনুগ্রহ করে এই নির্দেশিকা অনুযায়ী তা করুন৷

আগত অনুরোধ - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

বহির্গামী প্রতিক্রিয়া - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google অনুরোধ - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google প্রতিক্রিয়া - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

এখানে একটি পিজিপি লাইব্রেরি এবং জাভাতে নমুনা রয়েছে যা হ্যান্ডলিং অনুরোধ এবং প্রতিক্রিয়া দেখায়।

অদম্য আচরণ অনুসরণ করুন

ইডমপোটেন্সির অর্থ হল আপনার এমন কোনও অনুরোধ (যেমন অর্থপ্রদান) পুনঃপ্রক্রিয়া করার চেষ্টা করা উচিত নয় যা ইতিমধ্যেই সফলভাবে প্রক্রিয়া করা হয়েছে। এর পরিবর্তে সফল প্রক্রিয়াকরণের প্রতিক্রিয়া প্রতিবেদন করা উচিত।

কেন এটা গুরুত্বপূর্ণ

আমাদের পাশের রাজ্যটি বিক্রেতার পাশের রাজ্যের মতোই কিনা তা নিশ্চিত করতে 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"
}

রেমিট্যান্স বাস্তবায়ন করুন

একবার আপনি আপনার নির্দিষ্ট FOP-এর জন্য APIগুলিকে একীভূত করলে, আপনি রেমিট্যান্সের জন্য প্রস্তুত। রেমিট্যান্স সমস্ত FOP তে একই কাজ করে।

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 )

পুনর্মিলনের জন্য, ইন্টিগ্রেটর রেমিট্যান্স স্টেটমেন্ট নোটিফিকেশনে অন্তর্ভুক্ত ইভেন্টের তালিকা পেতে রেমিট্যান্স স্টেটমেন্ট ডিটেইলস কল করবে।

Google ইভেন্টের একটি পৃষ্ঠাযুক্ত তালিকা সহ remittanceStatementDetails অনুরোধে সাড়া দেয়। মোট লেনদেনের সংখ্যা 1000-এর বেশি হলে remittanceStatementDetails একাধিকবার কল করা উচিত। অনুরোধগুলি ক্রমানুসারে করার দরকার নেই, এবং সমান্তরাল করা যেতে পারে।

অনুরোধ 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 অ্যাকাউন্টে আপনার ব্যাঙ্ক স্থানান্তর শুরু করুন।

acceptRemittanceStatement জন্য URL অনুরোধ করুন

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

acceptRemittanceStatementWithModifications করার জন্য URL অনুরোধ করুন

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