Game Top-Up API — order processing flow
Top-up digital goods की इकलौती ऐसी श्रेणी है जहाँ आप माल नहीं, किसी और के account पर एक क्रिया देते हैं। कोई code नहीं, कोई undo नहीं, और पाने वाला उस string से तय होता है जो खरीदार ने हाथ से टाइप की। नीचे ऐसे order का पूरा processing flow है और वे जगहें जहाँ यह फ़र्क़ keys बेचने से copy की गई architecture को तोड़ देता है।
Top-up code से कैसे अलग है
| गुण | Gift card / key | Account top-up |
|---|---|---|
| सप्लायर क्या लौटाता है | Code string | Credit की पुष्टि |
| माल रोक सकते हैं? | हाँ, code आपके पास रहता है | नहीं, credit तुरंत और लक्षित है |
| पाने वाला तय होता है | जिसे आपने code दिया | खरीदार के डाले ID से |
| पूरा होने के बाद reversal | कभी-कभी issuer से संभव | व्यावहारिक रूप से असंभव |
| मुख्य जोख़िम | Code redeem नहीं होता | Currency ग़लत account में चली गई |
इससे मुख्य design नियम निकलता है: पूरी सुरक्षा पैसे लेने से पहले वाले चरण में चली जाती है। Codes में आप बहुत कुछ बाद में ठीक कर सकते हैं। Top-ups में लगभग कुछ नहीं।
चरण 1. Charge से पहले player ID validation
यह पूरी integration का सबसे अहम हिस्सा है और पूरी तरह आपकी तरफ़ रहता है।
Format validation
पैसे लेने से पहले न्यूनतम जाँच:
- लंबाई और character set. हर game का identifier format अलग है — कहीं सिर्फ़ अंक, कहीं alphanumeric, कहीं separator के साथ।
- Server या region. कई games ID के साथ server या zone माँगती हैं। इसके बिना top-up ग़लत जगह जाएगा या बिल्कुल fail होगा।
- कचरा हटाएँ. आगे-पीछे की खाली जगह, paste हुआ «ID:» prefix, messenger से आए फ़ालतू characters। भेजने से पहले string normalize करें।
Account existence check
कुछ सप्लायर identifier check का अलग endpoint देते हैं जो player का nickname लौटाता है। कुछ नहीं देते, और यह game पर भी निर्भर करता है। अपने सप्लायर से पूछें कि आपकी games के लिए यह जाँच उपलब्ध है या नहीं।
जहाँ उपलब्ध हो वहाँ उसे ज़रूर इस्तेमाल करें और payment से पहले खरीदार को nickname दिखाएँ। यह dispute रोकने का सबसे सस्ता तरीक़ा है: जो व्यक्ति किसी अजनबी का नाम देख लेता है, वह अपना ID ख़ुद ठीक कर लेता है।
खरीदार की पुष्टि
Nickname lookup न भी हो, तब भी debit से पहले confirmation screen अनिवार्य है। उस पर दिखे:
- ID ठीक उसी रूप में जिस रूप में वह सप्लायर को जाएगा।
- Region या server।
- साफ़ शब्दों में यह कि credit अपरिवर्तनीय है।
- Confirmation का timestamp, जो आपके log में जाता है।
यही log आपका जवाब है जब खरीदार हफ़्ते भर बाद कहे कि उसने दूसरा नंबर टाइप किया था।
चरण 2. Order बनाना
Order बाक़ी सब की तरह बनता है, बस line item में अतिरिक्त data जाता है:
curl -X POST "https://public-api.foxreload.com/api/orders" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"itemId": "product_01krgfgww8eth9xvvysd6y7r4j",
"quantity": 1,
"note": {"player_id": "123456"}
}
],
"isMock": false
}'
FoxReload में player identifier line item के note field में जाता है — यह object अतिरिक्त data की 10 keys तक लेता है। कोई product कौन-सी keys चाहता है, यह उसके attributes और userGuide में लिखा होता है।
Idempotency के बारे में। कुछ API Idempotency-Key header स्वीकार करते हैं ताकि दोबारा भेजने पर दूसरा order न बने। जाँचें कि आपका सप्लायर इसे लागू करता है या नहीं — बहुत से नहीं करते। FoxReload नहीं करता, इसलिए order creation पर timeout आने पर आँख मूँदकर retry नहीं करना चाहिए: पहले order list माँगकर पुष्टि करें कि कुछ बना तो नहीं। Top-ups में इस ग़लती की क़ीमत codes से ज़्यादा है — duplicate का मतलब दूसरा credit है जो कभी वापस नहीं आएगा।
चरण 3. Asynchronous completion
Order क्रम से और एक ही दिशा में states से गुज़रता है:
| State | अर्थ | आपका system क्या करे |
|---|---|---|
active |
Order बना, balance debit बाक़ी | order_id दर्ज करें, polling शुरू करें |
paid |
Balance debit हो गया | कुछ नहीं, इंतज़ार करें |
processing |
सप्लायर account में credit कर रहा है | Backoff के साथ polling जारी रखें |
completed |
Currency account में जमा हो गई | खरीदार को सूचित करें, order बंद करें |
cancelled |
Order रद्द, cancelReason देखें |
खरीदार को refund करें |
failed |
Fulfilment विफल, items[].error देखें |
कारण वर्गीकृत करें, refund या retry तय करें |
Status polling से मिलता है:
curl "https://public-api.foxreload.com/api/orders/{order_id}" \
-H "X-API-Key: YOUR_API_KEY"
जाँचें कि आपका सप्लायर webhooks देता है या नहीं। देता हो तो उसे accelerator की तरह इस्तेमाल करें पर polling को source of truth बनाए रखें, क्योंकि delivery की गारंटी कभी नहीं होती। FoxReload webhooks support नहीं करता, इसलिए यहाँ polling ही एकमात्र mechanism है।
Polling की शक्ल: पहले मिनट में बार-बार, फिर बढ़ता अंतराल, अपनी deadline और उससे आगे निकले orders के लिए queue। यह queue top-ups में सबसे ज़्यादा मायने रखती है — जिस खरीदार को game में currency नहीं दिख रही, वह key का इंतज़ार करने वाले से जल्दी support में लिखता है।
ऐसी state machines के design का गहरा विश्लेषण order state machine वाले लेख में है।
चरण 4. Terminal बनाम retryable failures
Failures को दो वर्गों में बाँटना ही काम करने वाली integration को पैसा जलाने वाली से अलग करता है।
Terminal — retry बेकार है
- ग़लत player ID. Account मौजूद नहीं या format ग़लत। Retry वही जवाब देगा। खरीदार को refund करें, ID जाँचने को कहें।
- Region support नहीं. उस region के account में यह product credit नहीं हो सकता। Refund।
- उस account के लिए product अनुपलब्ध. जैसे कोई bundle जो एक स्तर से नीचे के players को या उस देश में नहीं बिकता।
- Auth और request validation errors —
HTTP 400,401,403। यह आपकी bug है, outage नहीं।
Terminal failure पर order को polling loop से तुरंत हटाएँ और refund path को सौंप दें।
Retryable — दोबारा कोशिश सार्थक है
HTTP 429— rate limit पार। Jitter के साथ exponential backoff।HTTP 5xx— सप्लायर की तरफ़ गड़बड़ी। Backoff, सीमित attempts।- Network timeout. यहाँ विशेष सावधानी: पहले order की state जाँचें, फिर तय करें।
- Game की अस्थायी अनुपलब्धता. Publisher का maintenance अटके
processingकी जानी-पहचानी वजह है। इंतज़ार करें, order दोबारा मत बनाएँ।
शुरुआत में लगभग सब यही ग़लती करते हैं: timeout को retryable मानकर तुरंत नया order बना देना। Top-ups में इसका मतलब है double credit और वह पैसा जो कभी वापस नहीं आएगा।
चरण 5. Refunds और reversals
यहाँ हक़ीक़त साफ़ मान लेनी चाहिए: credit का कोई automatic reversal होता ही नहीं।
परिस्थितियाँ और उनका इलाज:
- Credit से पहले order
cancelledयाfailedहुआ. आप अपने payment method से खरीदार को refund करते हैं; सप्लायर अपने नियमों के अनुसार आपके balance में पैसा लौटाता है — ये नियम पहले से पता कर लें। - Credit हो गया पर खरीदार असंतुष्ट है. माल दिया जा चुका है। यहाँ refund व्यावसायिक फ़ैसला है, तकनीकी operation नहीं।
- Credit उस ID पर गया जो खरीदार ने ग़लत डाला. तकनीकी रूप से अपरिवर्तनीय। आपकी स्थिति confirmation log है। इसीलिए confirmation screen वैकल्पिक नहीं है।
- Multi-line order का partial fulfilment. Lines को स्वतंत्र रूप से संभालें: जो पूरी हुईं वे रहने दें, जो नहीं हुईं उनका refund करें।
अपनी unit economics में विवादित मामलों के लिए छोटा reserve रखें। Volume पर ये टलते नहीं, और इन्हें अलग line item की तरह देखना margin में अचानक गिरावट से चौंकने से बेहतर है। इसका गणित reseller की unit economics में है।
चरण 6. Reconciliation
रोज़ाना reconciliation बुनियादी अनुशासन है, वैकल्पिक सुविधा नहीं।
सप्लायर की order list लें:
curl "https://public-api.foxreload.com/api/orders/?statuses=completed,failed,cancelled&limit=100" \
-H "X-API-Key: YOUR_API_KEY"
और अपने database से मिलाएँ। क्या ढूँढना है:
- सप्लायर के पास ऐसे orders जिनका आपके पास record नहीं. यह blind retry से बने duplicate का क्लासिक निशान है।
- आपके यहाँ अब भी चल रहे orders जो सप्लायर के यहाँ terminal हो चुके. आपका poller टूटा या process गिरा।
- रक़म का अंतर. Order के समय की क़ीमत आपके record से अलग है, यानी आप क़ीमत ग़लत क्षण पर दर्ज कर रहे हैं।
- बिना order के balance debit. तुरंत जाँचें।
Reconciliation समस्याएँ घंटों में सामने लाती है, महीने के अंत में नहीं जब मिलाने को कुछ बचता ही नहीं।
Top-ups थोक में कहाँ से लें
Top-ups वहीं से लेना समझदारी है जहाँ से बाक़ी range — कई की जगह एक integration। FoxReload एक थोक digital-goods सप्लायर है जिसके पास 900+ SKU हैं — game account top-ups, gift cards, keys, eSIM और software licences — सब एक ही REST API के पीछे, automated delivery और multi-region SKUs के साथ। सभी categories पर एक order model और एक status vocabulary, उन products समेत जिनमें player ID भेजना होता है।