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

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

उपयोग के उदाहरण

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

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

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

उपयोगकर्ता किसी सुविधा स्टोर जैसी किसी जगह पर नकद पैसे देकर, 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 वगैरह) दी थी, तो आपको उस अनुरोध को एक नए अनुरोध के तौर पर प्रोसेस करना चाहिए और उसकी फिर से जांच करनी चाहिए. अगर आपका सर्वर पहली बार में बंद था और फिर से कोशिश करने से अनुरोध को प्रोसेस होने का एक और मौका मिलता है, तो यह तरीका मददगार होता है.

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

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

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 नंबर पर कॉल करता है. हम उम्मीद करते हैं कि आप इस लेन-देन या खाते की पहचान करने वाली रेफ़रंस संख्या के साथ जवाब देंगे. अनुमानित इंतज़ार का समय < है 3 सेकंड.

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

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

यूआरएल: 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 भेजेगा. इसमें उस दिन रिकॉर्ड किए गए लेन-देन की खास जानकारी होगी. लेन-देन के दो दिनों के बाद, सूचना का सैंपल इस तरह दिखती है:

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 के अनुरोध का जवाब देता है. इसके जवाब में, इवेंट की पेजों की सूची बनाई जाती है. अगर कुल लेन-देन की संख्या 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"
}