डॉक्यूमेंटेशन

ब्राउज़र में एक स्क्रिप्ट, आपके सर्वर से एक API कॉल। लाइव होने के लिए जो कुछ चाहिए, सब एक ही पेज पर।

क्विक स्टार्ट

ब्राउज़र के लिए आपको अपनी public key (pk_...) और सर्वर के लिए अपनी secret key (sk_...) चाहिए। दोनों डैशबोर्ड में Sites and keys के अंदर मिलेंगी।

1. स्क्रिप्ट जोड़ें

यह टैग उन पेजों पर लगाएं जहां यूज़र साइन अप, लॉग इन, ऑफ़र क्लिक या कैशआउट रिक्वेस्ट करते हैं। यह खुद को इससे initialize करता है: data-key

<script src="https://cashoutguard.com/v1/agent.js" data-key="pk_live_YOUR_PUBLIC_KEY" async></script>

2. request_id कलेक्ट करके अपने सर्वर पर भेजें

ज़रूरी मौके पर इवेंट के नाम के साथ collect() कॉल करें। यह इसमें resolve होता है: { request_id, visitor_id }

const { request_id } = await CashoutGuard.collect({ event: 'cashout' });

collect() कभी reject नहीं होता। फ़ेल होने पर (ब्लॉक, ऑफ़लाइन, टाइमआउट) यह request_id: null और एक error string के साथ resolve होता है। फिर भी फ़ॉर्म भेजें और फ़ैसला अपने सर्वर को करने दें।

3. अपने सर्वर से फ़ैसला पूछें

इवेंट को /v1/evaluate पर POST करें और अपनी secret key इस हेडर में भेजें: Authorization: Bearer sk_live_...

Secret key को कभी भी ब्राउज़र कोड या मोबाइल ऐप में न डालें। /v1/evaluate सिर्फ़ आपका सर्वर ही कॉल करे।

Evaluate रिक्वेस्ट

POST https://cashoutguard.com/v1/evaluate एक अकाउंट के एक इवेंट को स्कोर करता है, उसे उसके डिवाइस, नेटवर्क और पेआउट एड्रेस से जोड़ता है, और एक decision लौटाता है। JSON भेजें।

फ़ील्ड	टाइप	ज़रूरी	विवरण
`event`	string	ज़रूरी	signup, login, offer_click, conversion, cashout या custom।
`account_id`	string	ज़रूरी	आपकी यूज़र ID, ज़्यादा से ज़्यादा 191 कैरेक्टर। ईमेल नहीं, कोई opaque ID इस्तेमाल करें।
`request_id`	string	वैकल्पिक	ब्राउज़र में collect() से मिलता है। 1 घंटे तक वैध। इसके बिना हमारे पास सिर्फ़ नेटवर्क डेटा होता है।
`ip`	string	वैकल्पिक	यूज़र का IP। तभी ज़रूरी जब आपके पास request_id न हो, जैसे postbacks के लिए।
`email`	string	वैकल्पिक	हैश के रूप में सेव होता है। डिस्पोज़ेबल डोमेन और अकाउंट्स के बीच शेयर किए गए ईमेल पकड़ता है।
`payout_address`	string	वैकल्पिक	PayPal ईमेल, वॉलेट या वो अकाउंट जिसमें पैसा जाता है। हैश के रूप में सेव होता है।
`payout_method`	string	वैकल्पिक	फ़्री टेक्स्ट, जैसे paypal, usdt या giftcard।
`amount`	number	वैकल्पिक	कैशआउट या कन्वर्ज़न की रकम।
`currency`	string	वैकल्पिक	करेंसी कोड, जैसे USD। कैशआउट के लिए डिफ़ॉल्ट USD है।
`offer_id`	string	वैकल्पिक	ऑफ़र ID, offer_click और conversion के लिए। ऑफ़र स्पीड के लिए इस्तेमाल होती है।
`offer_country`	string	वैकल्पिक	वह देश जिसके लिए ऑफ़र भुगतान करता है (ISO कोड, जैसे US), कन्वर्ज़न पर। दूसरे देश का यूज़र फ़्लैग होता है।
`geo_country`	string	वैकल्पिक	यूज़र के IP की आपकी अपनी जियोलोकेशन (ISO कोड)। हमसे अलग हो तो IP संभवतः प्रॉक्सी एग्ज़िट है।
`transaction_id`	string	वैकल्पिक	किसी कन्वर्ज़न की नेटवर्क ट्रांज़ैक्शन ID। डुप्लिकेट पकड़ने के लिए इस्तेमाल होती है।
`offer_name`	string	वैकल्पिक	ऑफ़र का शीर्षक, जैसा आपके यूज़र देखते हैं। डैशबोर्ड में ID की जगह यही दिखता है।
`click_id`	string	वैकल्पिक	आपकी क्लिक ID। offer_click और कन्वर्ज़न दोनों में एक ही मान भेजें ताकि वे जुड़ जाएँ।
`source`	string	वैकल्पिक	इवेंट कहाँ से आया, जैसे ऑफ़रवॉल या नेटवर्क का नाम।
`meta`	object	वैकल्पिक	इवेंट के साथ सेव होने वाले 20 तक अतिरिक्त टेक्स्ट फ़ील्ड (जैसे sub ID)।

रिस्पॉन्स

रिस्पॉन्स का ढांचा हमेशा एक जैसा रहता है। जो फ़ील्ड लागू नहीं होते, वे null होते हैं।

score 0 से 100 तक होता है। कारणों को इस तरह जोड़ा जाता है कि कई मीडियम सिग्नल मिलकर बढ़ें, पर 100 से ऊपर न जाएं।
reasons हर ट्रिगर हुए सिग्नल की लिस्ट देता है, सबसे मज़बूत पहले, उसके वेट, डिटेल्स और सीधे दिखाने लायक़ सरल अंग्रेज़ी लेबल के साथ।
device.confidence बताता है कि डिवाइस कितना यूनिक दिखता है। फ़िंगरप्रिंट स्पूफ़ किए जा सकते हैं, इसलिए हम कभी पक्का होने का दावा नहीं करते।
linked_accounts उन दूसरे अकाउंट्स की लिस्ट देता है जो इस अकाउंट के साथ डिवाइस, पेआउट एड्रेस या ईमेल शेयर करते हैं।
cashout सिर्फ़ cashout इवेंट्स के लिए सेट होता है और आपकी रिव्यू क्यू में स्टेटस बताता है।

Decisions और actions

decision पर नहीं, action फ़ील्ड के हिसाब से कदम उठाएं। नीचे दिए थ्रेशोल्ड डिफ़ॉल्ट हैं और डैशबोर्ड में हर साइट के लिए बदले जा सकते हैं।

Decision	स्कोर (डिफ़ॉल्ट)	shadow में action	enforce में action	क्या करें
`allow`	0-49	`allow`	`allow`	सामान्य रूप से आगे बढ़ें।
`review`	50-79	`allow`	`review`	कैशआउट होल्ड करें या अतिरिक्त वेरिफ़िकेशन मांगें। यह आपकी रिव्यू क्यू में दिखता है।
`block`	80-100	`allow`	`block`	एक्शन रोक दें। बैलेंस फ़्रीज़ करें या साइन अप रिजेक्ट करें।

Shadow मोड में action हमेशा allow होता है, इसलिए enforce करने से पहले भी वही कोड शिप करना सुरक्षित है। Enforce पर स्विच करने पर आपके कोड में कुछ नहीं बदलता।

इवेंट टाइप

आपके पास जो इवेंट हैं, वो भेजें। Signup और cashout सबसे अहम हैं; conversions से ऑफ़र स्पीड चेक चलते हैं।

इवेंट	कब भेजें	क्या पकड़ता है
`signup`	अकाउंट बना	मल्टी-अकाउंट, बॉट, VPN साइन अप, डिस्पोज़ेबल ईमेल
`login`	सफल लॉगिन	अकाउंट शेयरिंग, देश बदलना, नए डिवाइस
`offer_click`	यूज़र कोई ऑफ़र खोलता है	ऑफ़र स्पीड के लिए घड़ी शुरू करता है
`conversion`	Offerwall या नेटवर्क से postback	बहुत तेज़ पूरे हुए ऑफ़र, डुप्लिकेट ट्रांज़ैक्शन, कन्वर्ज़न की बाढ़
`cashout`	यूज़र विड्रॉल रिक्वेस्ट करता है	शेयर किए गए पेआउट एड्रेस, कैशआउट वेलोसिटी, नए अकाउंट से कैशआउट
`custom`	कुछ भी और जिसे आप स्कोर कराना चाहें	डिवाइस और नेटवर्क सिग्नल

ऑफ़रवॉल और पोस्टबैक

ऑफ़रवॉल कन्वर्ज़न पोस्टबैक से, सर्वर से सर्वर, बिना ब्राउज़र के आते हैं। CashoutGuard हर कन्वर्ज़न को उसे शुरू करने वाले क्लिक से जोड़ता है, इसलिए उसका स्कोर उसी क्लिक के डिवाइस और नेटवर्क से बनता है।

1. जब यूज़र कोई ऑफ़र खोलता है

ब्राउज़र में कलेक्ट करें और ऑफ़र व अपनी क्लिक ID के साथ offer_click भेजें।

2. जब पोस्टबैक आता है

अपने पोस्टबैक हैंडलर से उसी account_id और click_id के साथ conversion भेजें। request_id की ज़रूरत नहीं। अगर ऑफ़रवॉल यूज़र का IP देता है तो उसे भी भेजें।

कन्वर्ज़न की जाँच होती है: ऑफ़र के लिए बहुत तेज़ पूरा होना, बिना क्लिक का कन्वर्ज़न, क्लिक और कन्वर्ज़न अलग देशों से, अकाउंट के सामान्य दिन से बहुत ज़्यादा कमाई, और डुप्लिकेट ट्रांज़ैक्शन ID।

ऑफ़रवॉल नेटवर्क

अगर आप कई पब्लिशर्स वाला नेटवर्क चलाते हैं, तो पब्लिशर सहित अकाउंट ID भेजें और Sites में "ऑफ़रवॉल नेटवर्क मोड" चालू करें। तब अकाउंट केवल उसी पब्लिशर के भीतर जुड़ते हैं, क्योंकि एक व्यक्ति का कई पब्लिशर्स की साइटें इस्तेमाल करना सामान्य है। फ़ॉर्मैट: publisher_id:user_id

ऑफ़र कैटलॉग

POST /v1/offers आपके ऑफ़र के नाम भेजता है (हर कॉल में 1,000 तक)। पुराने और नए इवेंट असली नाम दिखाएँगे, भले ही उनमें केवल ID हो।

रीज़न कोड

ये कोड reasons[].code में आते हैं। अपने मॉडरेटर्स को टेक्स्ट दिखाएं; अपने लॉजिक में कोड इस्तेमाल करें।

कोड	मतलब	ग्रुप	वेट
`ip_tor`	Tor एग्ज़िट नोड	नेटवर्क	60
`ip_vpn`	VPN कनेक्शन	नेटवर्क	45
`ip_datacenter`	डेटासेंटर / होस्टिंग IP	नेटवर्क	40
`timezone_mismatch`	ब्राउज़र का टाइमज़ोन IP लोकेशन से मेल नहीं खाता	नेटवर्क	20
`webrtc_ip_leak`	असली IP किसी दूसरे देश में लीक हुआ	नेटवर्क	30
`ip_multi_timezone`	एक ही IP पर कई अलग टाइमज़ोन (प्रॉक्सी एग्ज़िट)	नेटवर्क	50
`proxy_farm_ip`	एक IP पर कई खाते, सभी में एक ही विदेशी घड़ी (साझा प्रॉक्सी)	नेटवर्क	60
`provider_rotation`	कुछ दिनों में कई इंटरनेट प्रदाता, विदेशी घड़ी के साथ (घूमने वाला रेज़िडेंशियल प्रॉक्सी)	नेटवर्क	45
`privacy_relay`	iCloud Private Relay (प्राइवेसी फीचर)	नेटवर्क	5
`proxy_headers`	अनुरोध प्रॉक्सी से आया	नेटवर्क	20
`geo_sources_disagree`	जियोलोकेशन स्रोत मेल नहीं खाते	नेटवर्क	45
`ip_shared_with_accounts`	आज यही IP दूसरे अकाउंट्स ने भी इस्तेमाल किया	नेटवर्क	25
`country_changed`	देश बदल गया	नेटवर्क	15
`impossible_travel`	असंभव यात्रा: कुछ घंटों में दो दूर देशों के IP	नेटवर्क	50
`locale_country_mismatch`	दूसरे देश की ब्राउज़र भाषा	नेटवर्क	30
`phone_country_mismatch`	IP से अलग देश का फ़ोन	नेटवर्क	20
`ip_flagged_on_network`	दूसरी वेबसाइटों पर ब्लॉक IP	नेटवर्क	25
`device_shared_with_accounts`	डिवाइस दूसरे अकाउंट्स के साथ शेयर है	डिवाइस	55
`automation_detected`	बॉट या ऑटोमेशन टूल	डिवाइस	70
`auto_clicker`	फ़ोन पर ऑटो-क्लिकर	डिवाइस	55
`scripted_behavior`	स्क्रिप्ट से पेज का इस्तेमाल	डिवाइस	45
`emulator_or_vm`	एमुलेटर या वर्चुअल मशीन	डिवाइस	45
`browser_tampering`	ब्राउज़र से छेड़छाड़ / स्पूफिंग	डिवाइस	35
`device_rooted`	रूटेड फ़ोन	डिवाइस	25
`incognito`	प्राइवेट ब्राउज़िंग	डिवाइस	10
`device_spoofed`	नकली फ़ोन मॉडल	डिवाइस	55
`emulator_profile`	एमुलेटर का डिफ़ॉल्ट प्रोफ़ाइल	डिवाइस	60
`cloud_phone`	क्लाउड फ़ोन	डिवाइस	60
`phone_farm_display`	फ़ोन फ़ार्म डिस्प्ले	डिवाइस	45
`device_market_mismatch`	सिर्फ़ चीन वाला फ़ोन विदेश में	डिवाइस	25
`storage_cleared_reappeared`	कुकीज़ साफ़ करके फिर लौटा	डिवाइस	15
`no_device_data`	कोई डिवाइस डेटा नहीं भेजा गया	डिवाइस	15
`request_reused`	डिवाइस टोकन किसी दूसरे अकाउंट ने दोबारा इस्तेमाल किया	डिवाइस	40
`device_farm_proxy`	रेज़िडेंशियल प्रॉक्सी पर फ़ोन फ़ार्म	डिवाइस	85
`device_clones`	डिवाइस क्लोन: एक फ़ोन अपनी पहचान रीसेट करके एक नेटवर्क पर कई नए खाते बन रहा है	डिवाइस	55
`payout_address_shared`	पेआउट एड्रेस दूसरे अकाउंट्स भी इस्तेमाल कर रहे हैं	अकाउंट	70
`email_disposable`	डिस्पोज़ेबल ईमेल	अकाउंट	25
`email_invalid`	ऐसा ईमेल जिस पर मेल नहीं आ सकता (ऐसा कोई मेल डोमेन नहीं)	अकाउंट	35
`email_shared`	किसी दूसरे अकाउंट वाला ही ईमेल	अकाउंट	50
`phone_shared`	दूसरे अकाउंट के साथ साझा फ़ोन नंबर	अकाउंट	50
`phone_voip`	VoIP या वर्चुअल नंबर	अकाउंट	40
`phone_invalid`	अमान्य फ़ोन नंबर	अकाउंट	30
`many_devices_per_account`	एक अकाउंट पर बहुत ज़्यादा डिवाइस	अकाउंट	20
`flagged_on_network`	CashoutGuard से सुरक्षित अन्य वेबसाइटों पर चिह्नित	अकाउंट	45
`face_same_person`	दूसरे अकाउंट जैसा ही चेहरा	अकाउंट	0
`offer_completed_too_fast`	ऑफ़र नामुमकिन रफ़्तार से पूरा हुआ	बिहेवियर	40
`slow_after_click`	क्लिक के काफ़ी देर बाद कन्वर्ज़न	बिहेवियर	0
`conversion_velocity`	एक घंटे में बहुत ज़्यादा कन्वर्ज़न	बिहेवियर	30
`conversion_without_click`	आपकी वॉल से क्लिक के बिना कन्वर्ज़न	बिहेवियर	35
`click_conversion_country_mismatch`	एक देश से क्लिक, दूसरे देश से कन्वर्ज़न	बिहेवियर	30
`offer_country_mismatch`	ऑफ़र का देश यूज़र के देश से अलग	बिहेवियर	45
`click_velocity`	कुछ ही मिनटों में बहुत ज़्यादा ऑफ़र क्लिक	बिहेवियर	35
`earnings_spike`	आम यूज़र से कहीं ज़्यादा कमाई	बिहेवियर	30
`source_high_reversals`	ज़्यादा चार्जबैक वाला सोर्स	बिहेवियर	45
`offer_high_reversals`	ज़्यादा चार्जबैक वाला ऑफ़र	बिहेवियर	35
`duplicate_transaction`	डुप्लिकेट ट्रांज़ैक्शन ID	बिहेवियर	60
`offer_repeated_other_publisher`	यही ऑफ़र पहले ही किसी दूसरे पब्लिशर से किया जा चुका है	बिहेवियर	85
`offer_repeated_other_account`	यही ऑफ़र इस डिवाइस पर दूसरे अकाउंट से पहले ही किया गया	बिहेवियर	85
`offer_farm_burst`	फ़ार्म की लहर: कुछ घंटों में इस ऑफ़र पर फ़ार्म डिवाइस वाले कई नए खाते	बिहेवियर	30
`signup_burst`	साइनअप की बौछार: कई खाते अलग-अलग IP से कुछ सेकंड में बने	बिहेवियर	25
`face_check_required`	चेहरे की जाँच ज़रूरी है, अभी नहीं हुई	बिहेवियर	0
`face_check_failed`	चेहरे की जाँच फ़ेल	बिहेवियर	0
`publisher_farm_wave`	इसके पब्लिशर की फ़ार्म लहर: इस ऑफ़र पर भेजे गए ज़्यादातर नए खाते क्लाउड फ़ोन या एमुलेटर से आए	बिहेवियर	55
`cashout_velocity`	एक दिन में बहुत ज़्यादा कैशआउट	बिहेवियर	30
`new_account_cashout`	बिल्कुल नए अकाउंट से कैशआउट	बिहेवियर	20
`blocklisted`	आपकी ब्लॉकलिस्ट में	आपकी लिस्ट	100

वेट्स को noisy-OR से जोड़ा जाता है: score = 100 x (1 - product of (1 - weight/100))। 40 के दो सिग्नल 80 नहीं, 64 देते हैं। ब्लॉकलिस्ट मैच हमेशा 100 देता है।

Webhooks

डैशबोर्ड में वेबहुक URL सेट करें। block स्कोर वाले हर इवेंट (event.blocked), किसी अकाउंट के block होने (account.blocked) और आपकी टीम के कैशआउट फ़ैसले (cashout.decided) पर हम POST भेजते हैं। जो टाइप इस्तेमाल न करें उन्हें अनदेखा करें।

हर रिक्वेस्ट आपके webhook secret से साइन की जाती है। Raw body का hex HMAC-SHA256 इस हेडर में होता है: X-CashoutGuard-Signature

किसी भी 2xx स्टेटस के साथ जवाब दें। फ़ेल हुई डिलीवरी 5 बार तक दोबारा भेजी जाती है: 10 सेकंड, 1 मिनट, 5 मिनट और 15 मिनट बाद।

अकाउंट स्टेटस

GET /v1/accounts/{account_id} इवेंट बनाए बिना किसी अकाउंट का मौजूदा रिस्क व्यू लौटाता है।

POST /v1/accounts/{account_id}/status आपके अपने मॉडरेशन टूल्स को किसी अकाउंट का स्टेटस बदलने देता है।

active: नॉर्मल स्कोरिंग।
allowlisted: स्कोर रिव्यू थ्रेशोल्ड से नीचे सीमित रहते हैं। भरोसेमंद यूज़र्स और स्टाफ़ के लिए।
blocked: हर इवेंट स्कोर 100 के साथ block लौटाता है।

रिवर्सल और सटीकता

POST /v1/outcomes बताता है कि स्कोर के बाद कन्वर्ज़न का क्या हुआ: ऑफ़रवॉल या विज्ञापनदाता ने रिवर्स किया (chargeback) या वैध माना। हम आपके ids मिलाकर Accuracy पेज पर आपके ट्रैफ़िक पर इंजन मापते हैं।

बिना कोड: Accuracy पेज पर अपने ऑफ़रवॉल का मासिक रिवर्सल एक्सपोर्ट (CSV या Excel) अपलोड करें। id कॉलम हम खुद ढूंढ लेते हैं।

PHP, Node.js, Python, Android

किसी SDK की ज़रूरत नहीं। छोटे टाइमआउट वाली एक सादी HTTP कॉल काफ़ी है। कैशआउट का पूरा उदाहरण:

cashoutguard.php: PHP 7.4+, एक फ़ाइल, Composer नहीं। बस require करें।
composer require cashoutguard/cashoutguard-php: वही PHP क्लाइंट README के साथ, आपके vendor फ़ोल्डर के लिए।
npm install @cashoutguard/node: Node 18+, TypeScript टाइप्स के साथ।
cashoutguard-wordpress.zip: WordPress प्लगइन: हर पेज पर ब्राउज़र स्क्रिप्ट, साइनअप और लॉगिन का स्कोर, और कैशआउट, ऑफ़रवॉल कन्वर्ज़न व रिवर्सल के लिए हुक।

एरर और लिमिट

HTTP	बॉडी	मतलब
401	`missing_or_invalid_secret_key`	Secret key नहीं है, गलत है या रद्द की जा चुकी है। जवाब में कारण "reason" (missing, public_key, unknown_secret, placeholder, malformed) में और सुधार "hint" में होता है।
404	`not_found`	अकाउंट नहीं मिला (account endpoints)।
422	`{ "message", "errors" }`	बॉडी अमान्य है। errors हर फ़ील्ड की लिस्ट देता है।
429	`Too Many Requests`	रेट लिमिट पूरी हो गई। सर्वर API हर साइट के लिए प्रति मिनट 3,000 रिक्वेस्ट की अनुमति देता है।
401 · agent.js	`unknown_public_key`	data-key किसी साइट की पब्लिक की नहीं है। Install से pk_live_... फिर से कॉपी करें।
403 · agent.js	`origin_not_allowed`	पेज का डोमेन साइट के allowed origins में नहीं है। Sites में जोड़ें या सूची खाली छोड़ दें। localhost हमेशा चलता है। agent.js ब्राउज़र कंसोल में भी यह बताता है। ऐप के WebView "null" origin भेजते हैं: इन्हें स्वीकार करने के लिए सूची में null जोड़ें। नेटिव Android SDK को कुछ नहीं चाहिए।
403	`account_suspended`	अकाउंट सस्पेंड है, आम तौर पर बकाया बिल की वजह से। Billing देखें।
503	`temporarily_unavailable`	हमारी तरफ़ छोटी रुकावट। एक्शन होने दें और बाद में फिर कोशिश करें।

Fail open: अगर कॉल टाइमआउट हो या एरर आए, तो एक्शन को allow करें और लॉग कर लें। हमारे आउटेज की वजह से अपने यूज़र्स को कभी न रोकें।