प्रोडक्ट API सिंगल वॉलेट बनाम ट्रांसफ़र वॉलेट

सिंगल वॉलेट बनाम ट्रांसफ़र वॉलेट

ऑपरेटर के प्लेयर बैलेंस को कैसीनो गेम API से जोड़ने वाले दो वॉलेट मॉडल की तकनीकी तुलना: पैसा कौन रखता है, बेट के दौरान कौन-से कॉल नेटवर्क पर होते हैं, फ़ेल्योर से कैसे रिकवर किया जाता है, और आपको अपनी ओर से क्या बनाना होगा।

एक नज़र में

पहलू	सिंगल वॉलेट	ट्रांसफ़र वॉलेट
बैलेंस की कस्टडी	एकमात्र बैलेंस आपके डेटाबेस में रहता है। प्रोवाइडर कभी प्लेयर के फंड नहीं रखता।	प्रोवाइडर अलग गेम बैलेंस रखता है। फंड ट्रांसफ़र कॉल के ज़रिए अंदर-बाहर जाते हैं।
बेट के दौरान कॉल	हर बेट और जीत पर आपको सर्वर-टू-सर्वर कॉलबैक (बैलेंस, डेबिट, क्रेडिट, रोलबैक) भेजा जाता है।	कोई नहीं। गेम प्रोवाइडर-साइड बैलेंस पर चलता है। कॉल केवल ट्रांसफ़र इन और आउट के समय होते हैं।
आवश्यक उपलब्धता	आपके वॉलेट एंडपॉइंट को हर कॉलबैक का जवाब देना होगा, आमतौर पर कुछ सौ मिलीसेकंड के भीतर। ये डाउन हुए तो गेम रुक जाता है।	केवल ट्रांसफ़र के लिए ज़रूरी। आपका सिस्टम कुछ देर ऑफ़लाइन रहे तो भी राउंड चलते रहते हैं।
कंसिस्टेंसी मॉडल	आपका लेजर रियल-टाइम में सत्य का एकमात्र स्रोत है। केवल गेम राउंड का रिकंसिलिएशन करना होता है, बैलेंस का नहीं।	दो लेजर जो केवल ट्रांसफ़र की सीमाओं पर मेल खाते हैं। ट्रांसफ़र-स्तर पर रिकंसिलिएशन ज़रूरी है।
फ़ेल्योर रिकवरी	टाइमआउट को ट्रांज़ैक्शन ID पर आधारित आइडेम्पोटेंट रीट्राई और रोलबैक कॉल से हल किया जाता है।	ट्रांसफ़र दो चरणों में होते हैं: पेंडिंग, फिर सफल या असफल। अनिश्चित नतीजे का पता स्टेटस क्वेरी से चलता है।
इंटीग्रेशन में मेहनत	ज़्यादा। आपको आइडेम्पोटेंसी और लेजर के साथ कम-लेटेंसी वाली कॉलबैक सर्विस बनानी और चलानी होती है।	कम। आप तीन-चार REST एंडपॉइंट कॉल करते हैं, इनबाउंड ट्रैफ़िक को सुरक्षित या स्केल करने की ज़रूरत नहीं।
प्लेयर अनुभव	एक ही बैलेंस, कोई ट्रांसफ़र स्टेप नहीं। बोनस, क्रॉस-प्रोडक्ट प्ले और लाइव बैलेंस डिस्प्ले के लिए उपयुक्त।	खेलने से पहले फंड अंदर और बाद में बाहर ट्रांसफ़र करने पड़ते हैं। इससे थोड़ी देरी होती है, और प्लेयर बीच सेशन में छोड़ दे तो बैलेंस अटक सकता है।
आमतौर पर उपयुक्त	ऐसे ऑपरेटर जिनके पास अपना वॉलेट या प्लेटफ़ॉर्म है और जो फंड और प्रमोशन पर सख़्त नियंत्रण चाहते हैं।	ऐसे ऑपरेटर जो तेज़ लॉन्च चाहते हैं या जिनके पास रियल-टाइम वॉलेट सर्विस नहीं है।

सिंगल वॉलेट (सीमलेस)

सिंगल वॉलेट (सीमलेस) मॉडल में आपका सिस्टम ही वॉलेट होता है। जब कोई प्लेयर बेट लगाता है, तो SSG API आपके कॉलबैक एंडपॉइंट को कॉल करता है, आप अपने लेजर में बैलेंस बदलते हैं और नया बैलेंस लौटाते हैं। कोई भी फंड आपके डेटाबेस से बाहर नहीं जाता।

कॉल फ़्लो

लॉन्च: आपका बैकएंड प्लेयर ID और सेशन टोकन के साथ SSG से गेम URL माँगता है।
बेट: हर राउंड के लिए SSG यूनिक txId के साथ debit कॉल करता है। आप फंड जाँचते हैं, लेजर में एंट्री लिखते हैं और नया बैलेंस लौटाते हैं।
जीत: उसी राउंड के लिए SSG पेआउट (जो शून्य भी हो सकता है) के साथ credit कॉल करता है।
फ़ेल्योर: कॉल टाइमआउट हो जाए तो SSG उसी txId के साथ रीट्राई करता है, और रीट्राई सीमा पार होने पर rollback भेजता है।

कॉलबैक मेथड (उदाहरण)

मेथड	उद्देश्य	मुख्य फ़ील्ड	आइडेम्पोटेंट
`balance`	प्लेयर का मौजूदा बैलेंस लौटाएं।	`playerId, currency`	हाँ (केवल पढ़ने के लिए)
`debit`	बेट लगाएं: राशि घटाएं।	`playerId, txId, roundId, gameId, amount, currency`	txId के आधार पर
`credit`	जीत सेटल करें: राशि जोड़ें।	`playerId, txId, roundId, amount, currency`	txId के आधार पर
`rollback`	त्रुटि के बाद पिछला डेबिट या क्रेडिट रद्द करें।	`txId, refTxId`	txId के आधार पर

debit रिक्वेस्ट का उदाहरण

{
  "method": "debit",
  "playerId": "p_839201",
  "txId": "tx_20261007_000184",
  "roundId": "r_77f3a1",
  "gameId": "slots_fruit_01",
  "currency": "MYR",
  "amount": "2.50",
  "ts": 1791338577,
  "sign": "hex(HMAC-SHA256(secret, canonical))"
}

रिस्पॉन्स का उदाहरण

{
  "status": "OK",
  "txId": "tx_20261007_000184",
  "balance": "97.50",
  "currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
//         DUPLICATE_TX (return original result), INTERNAL_ERROR

आपकी वॉलेट सर्विस को इन नियमों का पालन करना होगा

आइडेम्पोटेंसी: एक ही txId के साथ दोबारा आया debit या credit मूल नतीजा लौटाए और पैसे को दोबारा न हिलाए। इसे txId पर यूनिक इंडेक्स लगाकर सुनिश्चित करें।
एटॉमिक लेजर राइट: बैलेंस जाँचना, लेजर एंट्री जोड़ना और बैलेंस अपडेट करना, तीनों एक ही डेटाबेस ट्रांज़ैक्शन में करें, ताकि एक साथ आई दो बेट से कभी ओवरड्रॉ न हो।
debit से पहले rollback: मूल debit टाइमआउट हो जाने पर ऐसे txId का rollback पहले आ सकता है जो आपने कभी देखा ही नहीं। एक टॉम्बस्टोन रिकॉर्ड सहेजें, ताकि उसी txId का देर से आया debit अस्वीकार हो जाए।
लेटेंसी बजट: नेटवर्क सहित p99 को 500 ms से कम रखने का लक्ष्य रखें। कॉलबैक पाथ में केवल एक इंडेक्स्ड रीड और एक राइट रखें, और रिपोर्टिंग क्वेरी को इससे दूर रखें।
राशि का फ़ॉर्मेट: राशि को डेसिमल स्ट्रिंग या पूर्णांक न्यूनतम इकाई (minor units) के रूप में संभालें। फ़्लोटिंग पॉइंट का कभी उपयोग न करें, और करेंसी को प्लेयर अकाउंट से मिलाकर सत्यापित करें।
बोनस और फ्री स्पिन: फ्री स्पिन में पहले 0 राशि का debit होता है, फिर जीत की राशि का credit। अपने लेजर में प्रमोशनल बैलेंस को कैश बैलेंस से अलग रखें।
सुरक्षा: कैनॉनिकल रिक्वेस्ट पर HMAC-SHA256 सिग्नेचर सत्यापित करें, पुराने टाइमस्टैम्प अस्वीकार करें, केवल SSG के सोर्स IP को अनुमति दें, और TLS 1.2 या उससे ऊपर अनिवार्य करें।
रिकॉन्सिलिएशन: SSG की दैनिक राउंड रिपोर्ट का अपने लेजर से roundId के आधार पर मिलान करें। अंतर का कारण आमतौर पर छूटे हुए कॉलबैक या रोलबैक होते हैं।

ट्रांसफ़र वॉलेट

ट्रांसफ़र वॉलेट मॉडल में प्रोवाइडर हर प्लेयर का गेम बैलेंस अपने पास रखता है। आपका बैकएंड खेल से पहले फ़ंड अंदर भेजता है और बाद में बाहर निकालता है। खेल के दौरान आपके सिस्टम पर कोई कॉलबैक नहीं आता, इसलिए आपको केवल आउटबाउंड REST कॉल की ज़रूरत होती है।

कॉल फ़्लो

ट्रांसफ़र इन: आपका बैकएंड अनूठे txId और राशि के साथ transferIn कॉल करता है। नतीजा PENDING या SUCCESS होता है।
प्ले: गेम लॉन्च करें। सभी बेट और जीत केवल प्रोवाइडर-साइड बैलेंस बदलती हैं, आपको कोई कॉलबैक नहीं मिलता।
ट्रांसफ़र आउट: प्लेयर के जाने पर पूरे बैलेंस के लिए transferOut कॉल करें और SUCCESS मिलने पर उसे अपने लेजर में वापस क्रेडिट करें।
अज्ञात नतीजा: अगर ट्रांसफ़र कॉल टाइमआउट हो जाए, तो कुछ और करने से पहले उसी txId से getTransferStatus क्वेरी करें।

API मेथड (उदाहरण)

मेथड	उद्देश्य	मुख्य फ़ील्ड	आइडेम्पोटेंट
`transferIn`	फ़ंड को आपके वॉलेट से प्लेयर के गेम बैलेंस में भेजें।	`playerId, txId, amount, currency`	txId के आधार पर
`transferOut`	फ़ंड को गेम बैलेंस से वापस आपके वॉलेट में भेजें।	`playerId, txId, amount \| all`	txId के आधार पर
`getBalance`	प्लेयर का गेम बैलेंस पढ़ें।	`playerId`	हाँ (केवल पढ़ने के लिए)
`getTransferStatus`	किसी txId के लिए PENDING, SUCCESS या FAILED लौटाएं।	`txId`	हाँ (केवल पढ़ने के लिए)

आपके बैकएंड को ये नियम मानने होंगे

हर इरादे के लिए एक txId: पहली कॉल से पहले txId बनाएं और हर रीट्राई में उसी का उपयोग करें। पिछले txId की स्थिति पता चलने तक नया txId कभी न बनाएं।
पहले अपना लेजर डेबिट करें: ट्रांसफ़र इन के लिए SSG को कॉल करने से पहले अपने लेजर में राशि रिज़र्व करें, फिर स्थिति अंतिम होने पर उसे कन्फ़र्म या रिलीज़ करें।
अटके हुए बैलेंस साफ़ करें: ऐसा जॉब चलाएं जो गेम बैलेंस वाले लेकिन बिना सक्रिय सेशन के प्लेयर ढूंढे और उनका बैलेंस ट्रांसफ़र आउट करे। यह उन प्लेयर को कवर करता है जो सेशन के बीच में ब्राउज़र बंद कर देते हैं।
वेजरिंग और रिपोर्ट: चूंकि आपको बेट लाइव नहीं दिखतीं, इसलिए टर्नओवर, बोनस वेजरिंग और रिस्क लिमिट की गणना कॉलबैक से नहीं, बल्कि SSG से खींची गई राउंड रिपोर्ट से करें।
रिकॉन्सिलिएशन: हर ट्रांसफ़र इन और आउट का SSG रिकॉर्ड से txId के आधार पर मिलान करें, और आपके टाइमआउट से पुराने किसी भी PENDING पर अलर्ट लगाएं।
सुरक्षा: रिक्वेस्ट पर HMAC-SHA256 से साइन करें, केवल TLS 1.2 या उससे ऊपर पर कॉल करें, API कुंजियां सीक्रेट स्टोर में रखें, और सीमित करें कि आपके कौन-से सर्वर SSG को कॉल कर सकते हैं।

फ़ेल्योर परिदृश्य

परिदृश्य	सिंगल वॉलेट	ट्रांसफ़र वॉलेट
नेटवर्क टाइमआउट	बेट के दौरान SSG उसी txId से रीट्राई करता है, और सीमा पूरी होने पर rollback भेजता है। आपका सिस्टम आइडेम्पोटेंट होना चाहिए।	केवल ट्रांसफ़र प्रभावित होते हैं। उसी txId से getTransferStatus क्वेरी करें, फिर आगे की कार्रवाई करें।
आपका सिस्टम डाउन है	प्लेयर राउंड शुरू या जारी नहीं रख सकते। खुले राउंड रोलबैक कर दिए जाते हैं।	प्लेयर अपने मौजूदा गेम बैलेंस से खेलना जारी रख सकते हैं। नए ट्रांसफ़र ब्लॉक हो जाते हैं।
डुप्लिकेट रिक्वेस्ट	उस txId का सेव किया हुआ रिस्पॉन्स लौटाएं और कुछ भी न बदलें।	उस txId का सेव किया हुआ नतीजा लौटाएं और कुछ भी न बदलें।
राउंड के बीच में प्लेयर का कनेक्शन टूटना	राउंड प्रोवाइडर पर पूरा हो जाता है और credit सामान्य रूप से भेज दिया जाता है।	राउंड पूरा हो जाता है और फ़ंड ट्रांसफ़र आउट या स्वीप जॉब तक गेम बैलेंस में रहता है।
बैलेंस में अंतर	आमतौर पर छूटा हुआ कॉलबैक या रोलबैक। roundId के आधार पर राउंड रिपोर्ट की तुलना करने से पता चलता है।	आमतौर पर अटका हुआ या पेंडिंग ट्रांसफ़र। txId के आधार पर ट्रांसफ़र की तुलना करने से पता चलता है।

कौन-सा चुनें

सिंगल वॉलेट चुनें अगर

आप पहले से रियल-टाइम वॉलेट या लेजर सर्विस चला रहे हैं।
आपको स्पोर्ट्सबुक, कैसीनो और प्रमोशन में एक ही बैलेंस चाहिए।
आपको रिस्क, बोनस वेजरिंग या रिस्पॉन्सिबल गेमिंग लिमिट के लिए लाइव बेट डेटा चाहिए।
आपकी टीम हाई अवेलेबिलिटी वाली लो-लेटेंसी सर्विस चला सकती है।

ट्रांसफ़र वॉलेट चुनें अगर

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

कई ऑपरेटर लॉन्च के लिए पहले ट्रांसफ़र वॉलेट से शुरुआत करते हैं, फिर अपनी वॉलेट सर्विस तैयार होने पर सिंगल वॉलेट पर चले जाते हैं। बदलाव चरणबद्ध तरीके से कैसे होता है, यह हमसे पूछें।

इंटीग्रेशन चेकलिस्ट

पैसे को प्रभावित करने वाली हर कॉल के लिए txId पर यूनिक इंडेक्स और आइडेम्पोटेंट हैंडलर
HMAC सिग्नेचर जांच, टाइमस्टैम्प सहनसीमा और IP अलाउलिस्ट
डेसिमल-सेफ़ राशि और करेंसी वैलिडेशन
सैंडबॉक्स में टाइमआउट, रीट्राई और रोलबैक टेस्ट, जिनमें देर से आने वाला रीट्राई भी शामिल हो
roundId (सिंगल) या txId (ट्रांसफ़र) के आधार पर दैनिक रिकॉन्सिलिएशन जॉब
मॉनिटरिंग और अलर्ट: कॉलबैक लेटेंसी, एरर रेट, पेंडिंग ट्रांसफ़र, अटके हुए बैलेंस

इंटीग्रेशन इंजीनियर से बात करें

हम आपके इंजीनियरों को सैंडबॉक्स समझा सकते हैं और आपके प्लेटफ़ॉर्म के अनुकूल मॉडल चुनने में मदद कर सकते हैं। इंटीग्रेशन सात दिनों के भीतर पूरा होने की गारंटी है।

सेल्स को ईमेल करें Telegram पर चैट करें प्रोडक्ट API पर वापस जाएं

sales@ssggaming.com