कैश एफ़ओपी (यानी रेफ़रंस नंबर एपीआई) गाइड

यहां इस्तेमाल के कुछ अहम उदाहरण दिए गए हैं. साथ ही, कैश एफ़ओपी को लागू करने के लिए ज़रूरी दिशा-निर्देश और एपीआई भी दिए गए हैं.

इस्तेमाल के उदाहरण

रेफ़रंस नंबर एपीआई का कई तरह से इस्तेमाल किया जा सकता है. इस गाइड में, इस्तेमाल के दो उदाहरणों पर चर्चा की गई है. साथ ही, आपको इन्हें लागू करने के तरीके की जानकारी भी मिलेगी.

  • नकद - उपयोगकर्ता किसी जगह पर जाकर नकद पैसे चुकाता है.
  • वैन - उपयोगकर्ता, वर्चुअल खाता नंबर पर पैसे ट्रांसफ़र करता है.

नकद में पैसे चुकाने की सुविधा उपलब्ध है

उपयोगकर्ता शॉपिंग स्टोर जैसी किसी जगह पर नकद पैसे देकर Google से कोई चीज़ खरीद सकता है. लेन-देन की पहचान करने के लिए, उपयोगकर्ता को एक रेफ़रंस नंबर जनरेट करना होगा, ताकि वह स्टोर पर जाकर पैसे चुका सके. इसके अलावा, Google, लोगों को खरीदारी पूरी करने के निर्देश दिखाएगा. आम तौर पर, जैसे ही उपयोगकर्ता खरीदारी पूरी कर लेता है, इंटिग्रेटर, Google को इसकी सूचना देता है, ताकि Google प्रॉडक्ट को डिलीवर कर सके.

Google में आपका संपर्क, पेमेंट से जुड़े आपके निर्देशों का सैंपल मांगेगा. आपको मैसेज सेवा को ऑप्टिमाइज़ करने और उसे बेहतर बनाने के लिए, अपने Google प्रतिनिधि के साथ काम करना होगा.

Google जो उपयोगकर्ता अनुभव देना चाहता है वह यह है कि ग्राहकों के स्टोर से निकलते ही ऑर्डर डिलीवर कर दिया जाए. Google चाहता है कि ग्राहक के रेफ़रंस नंबर का पेमेंट करने के तीन मिनट के अंदर, Google को ReferenceNumberPaidNotification मिल जाए. रेफ़रंस नंबरपेड नोटिफ़िकेशन भेजने के बाद, इंटिग्रेटर के ज़रिए लेन-देन को रद्द नहीं किया जा सकता.

वैन

उपयोगकर्ता अपने बैंक खाते से किसी सामान के लिए पैसे चुका सकता है. Google, इंटिग्रेटर से एक वर्चुअल खाता नंबर मांगेगा. इसमें नंबर और निर्देश शामिल होंगे. इसके बाद, उपयोगकर्ता उस नंबर को कॉपी करेगा और ट्रांसफ़र की जाने वाली रकम के साथ-साथ, उसे अपने बैंकिंग ऐप्लिकेशन में भी डालेगा.

इंटिग्रेटर को यह पुष्टि करनी होगी कि ट्रांसफ़र की गई रकम, रेफ़रंस नंबर जनरेट करने के अनुरोध की रकम से मैच करती है. इसके बाद, Google को यह सूचना देनी होगी कि रेफ़रंस नंबर का पेमेंट कर दिया गया है.

एक बार Google को ReferenceNumberPaidNotification मिल जाने पर, Google प्रॉडक्ट को डिलीवर करेगा और इंटिग्रेटर के ज़रिए इस लेन-देन को वापस नहीं लिया जा सकता.

अपने सर्वर और Google के सर्वर के बीच मैसेज भेजना

अपने सर्वर और Google के सर्वर के बीच या इसके उलट तरीके से मैसेज भेजते समय, कृपया इन दिशा-निर्देशों का पालन करें.

आने वाला अनुरोध - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

आउटगोइंग जवाब - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google अनुरोध - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google जवाब - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

यह रही Java में PGP लाइब्रेरी और सैंपल, जो हैंडलिंग के अनुरोध और रिस्पॉन्स दिखाता है.

बिना पहचान वाले व्यवहार को अपनाएं

मुद्रा के अमान्य होने का मतलब है कि आपको पहले ही प्रोसेस किए जा चुके किसी अनुरोध (जैसे कि पेमेंट) को दोबारा प्रोसेस करने की कोशिश नहीं करनी चाहिए. इसके बजाय, प्रोसेस हो जाने के बाद के रिस्पॉन्स की रिपोर्ट की जानी चाहिए.

यह क्यों ज़रूरी है

Google कुछ अनुरोधों पर फिर से काम करके, यह पक्का कर सकता है कि हमारी ओर से दी गई जानकारी और वेंडर की ओर से दी गई स्थिति एक है. आपके सिस्टम को यह नहीं लगना चाहिए कि यह एक अन्य लेन-देन है. इसलिए, बिना किसी भेदभाव के जवाब देना बहुत ज़रूरी है. इसका मतलब है कि इंटिग्रेटर को किसी ऐसी चीज़ को फिर से प्रोसेस नहीं करना चाहिए जो पहले ही प्रोसेस हो चुकी हो. ऐसे मामले में, पिछले जवाब को ही भेजा जाना चाहिए.

पहचान में बदलाव करने की सुविधा लागू करने का तरीका

अगर Google फिर से कोशिश करता है, तो अनुरोध का आईडी वही होगा और कॉन्टेंट भी वही रहेगा, लेकिन टाइमस्टैंप अलग होगा. वही जवाब दें जो आपने पहले भेजा था. अगर आपका पहला जवाब 200 (पूरा हुआ) था, तो Google उसी जवाब की उम्मीद दूसरे टाइमस्टैंप के साथ करेगा.

अगर आपका पिछला जवाब कोई गड़बड़ी (400 या 500 वगैरह) था, तो आपको उस अनुरोध को नए अनुरोध के तौर पर प्रोसेस करना होगा और उसकी फिर से जांच करनी होगी. अगर आपका सर्वर पहली बार काम नहीं कर रहा था, तो यह तरीका मददगार होता है. सर्वर फिर से कोशिश करने पर, अनुरोध को प्रोसेस होने का एक और मौका मिल जाता है.

ज़्यादा जानने के लिए, यह ज़्यादा जानकारी वाली गाइड देखें.

पेमेंट इंटीग्रेटर खाता आईडी (PIAID) का इस्तेमाल करना

Google के साथ इंटिग्रेशन के लिए, Google की अलग-अलग कारोबारी इकाइयों के साथ इंटिग्रेशन की ज़रूरत पड़ सकती है. उदाहरण के लिए, Google Play एक इकाई है, दूसरी इकाई YouTube है, और Google Ads दूसरी इकाई है. इनमें से हर कॉन्फ़िगरेशन को दिखाने के लिए, अलग-अलग व्यापारी खाते शामिल होंगे.

Google में मौजूद हर इकाई से हर व्यापारी खाते की मैपिंग के लिए, Google पेमेंट इंटिग्रेटर खाता आईडी (पीआईएआईडी) उपलब्ध कराता है. कैश एफ़ओपी एपीआई का उदाहरण देखने के लिए, generateReferenceNumber देखें. यहां एक सैंपल दिया गया है, जो इस मैपिंग का इस्तेमाल करता है.

Google में मौजूद हर इकाई से हर व्यापारी खाते की मैपिंग के लिए, Google पेमेंट इंटिग्रेटर खाता आईडी (पीआईएआईडी) उपलब्ध कराता है. कैश एफ़ओपी एपीआई का इस्तेमाल करने के उदाहरण के लिए, 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 में आपके संपर्क की जानकारी से मिलता है और दूसरा आपका कारोबारी खाता.

इंटिग्रेटर के पास, सेवा देने वाले हर देश के हिसाब से अलग-अलग खाते भी हो सकते हैं. ऐसा, टैक्स के अलग-अलग कानूनों और एक देश से दूसरे देश के हिसाब से अलग-अलग तरह के टैक्स की वजह से हो सकता है. इस मामले में, हर देश के लिए एक और पीआईएआईडी जनरेट किया जा सकता है.

इंटिग्रेट करने के लिए एपीआई

यहां दिए गए एपीआई, रेफ़रंस नंबर जनरेट करने और पेमेंट की सूचना को मैनेज करते हैं.

ये एपीआई, भेजे गए पैसे और सेटलमेंट को मैनेज करते हैं.

आपको रेफ़रंस नंबर जनरेट करने और Google के साथ सेटलमेंट करने के लिए, ऊपर दिए गए सभी एपीआई इंटिग्रेट करने होंगे.

रेफ़रंस नंबर जनरेट करें

जब आप खरीदारी शुरू करते हैं, तो Google generateReferenceNumber को कॉल करता है. हम चाहते हैं कि आप लेन-देन या खाते की पहचान करने वाले रेफ़रंस नंबर के साथ जवाब दें. इंतज़ार का समय तीन सेकंड से कम होना चाहिए.

नकदी लेन-देन के लिए, रेफ़रंस नंबर में ज़्यादा से ज़्यादा 12 वर्ण हो सकते हैं.

यूआरएल: 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 किसी रेफ़रंस नंबर को रद्द कर सकता है और उस नंबर को उपयोगकर्ता से पेमेंट किए जाने से रोक सकता है. इस्तेमाल के उदाहरण का उदाहरण, ऐसा प्रमोशन है जिसकी समयसीमा खत्म हो गई है. इस अनुरोध का जवाब देने के बाद, आपको यह पक्का करना होगा कि रेफ़रंस नंबर का पेमेंट न किया जा सके.

अगर उपयोगकर्ता ने पहले ही पेमेंट की प्रक्रिया शुरू कर दी है, जैसे कि बिक्री की जगह से रेफ़रंस नंबर खोजना, तो आपके सर्वर को अनुरोध के मुख्य हिस्से में, एचटीटीपी 423 रिस्पॉन्स और एरर रिस्पॉन्स देना चाहिए. साथ ही, इसका स्टेटस USER_ACTION_IN_PROGRESS के रूप में होना चाहिए.

यूआरएल: 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 एंडपॉइंट यूआरएल:


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 को कॉल करेगा, ताकि उसे remittanceStatementवर में शामिल किए गए इवेंट की सूची मिल सके.

Google, remittanceStatementDetails अनुरोध का जवाब कई पेजों में बांटी गई इवेंट की सूची के साथ देता है. अगर कुल लेन-देन की संख्या 1,000 से ज़्यादा है, तो 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 के लिए यूआरएल का अनुरोध करें

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 के लिए यूआरएल का अनुरोध करें

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