CashoutGuard

ডকুমেন্টেশন

ব্রাউজারে একটি স্ক্রিপ্ট, আপনার সার্ভার থেকে একটি API কল। লাইভ হতে যা যা লাগবে, সব এক পেজে।

কুইক স্টার্ট

ব্রাউজারের জন্য আপনার পাবলিক কী (pk_...) আর সার্ভারের জন্য সিক্রেট কী (sk_...) লাগবে। দুটোই ড্যাশবোর্ডের Sites and keys অংশে আছে।

1. স্ক্রিপ্ট যোগ করুন

যে পেজগুলোতে ইউজাররা সাইন আপ, লগ ইন, অফারে ক্লিক বা ক্যাশআউট রিকোয়েস্ট করে, সেখানে এই ট্যাগটি বসান। এটি নিজে থেকেই ইনিশিয়ালাইজ হয় এখান থেকে: data-key

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

2. request_id সংগ্রহ করে আপনার সার্ভারে পাঠান

গুরুত্বপূর্ণ মুহূর্তে ইভেন্টের নাম দিয়ে collect() কল করুন। এটি রিজলভ হয়: { request_id, visitor_id }

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

collect() কখনো reject করে না। ব্যর্থ হলে (ব্লকড, অফলাইন, টাইমআউট) এটি request_id: null আর একটি এরর স্ট্রিং দিয়ে রিজলভ হয়। তবুও ফর্ম পাঠান, সিদ্ধান্ত আপনার সার্ভার নেবে।

3. আপনার সার্ভার থেকে সিদ্ধান্ত জেনে নিন

হেডারে আপনার সিক্রেট কী দিয়ে ইভেন্টটি /v1/evaluate-এ POST করুন: Authorization: Bearer sk_live_...

সিক্রেট কী কখনো ব্রাউজার কোড বা মোবাইল অ্যাপে রাখবেন না। শুধু আপনার সার্ভারই /v1/evaluate কল করবে।

Evaluate রিকোয়েস্ট

POST https://cashoutguard.com/v1/evaluate একটি অ্যাকাউন্টের একটি ইভেন্ট স্কোর করে, সেটিকে তার ডিভাইস, নেটওয়ার্ক আর পেআউট অ্যাড্রেসের সাথে যুক্ত করে এবং একটি সিদ্ধান্ত ফেরত দেয়। JSON পাঠান।

ফিল্ডটাইপআবশ্যকবিবরণ
eventstringআবশ্যকsignup, login, offer_click, conversion, cashout অথবা custom।
account_idstringআবশ্যকআপনার ইউজার ID, সর্বোচ্চ 191 অক্ষর। ইমেইল নয়, একটি অস্বচ্ছ (opaque) ID ব্যবহার করুন।
request_idstringঐচ্ছিকব্রাউজারের collect() থেকে পাওয়া। 1 ঘণ্টা বৈধ। এটি ছাড়া আমাদের কাছে শুধু নেটওয়ার্ক ডেটা থাকে।
ipstringঐচ্ছিকইউজারের IP। শুধু request_id না থাকলে দরকার, যেমন postback-এর ক্ষেত্রে।
emailstringঐচ্ছিকহ্যাশ করে রাখা হয়। ডিসপোজেবল ডোমেইন আর একাধিক অ্যাকাউন্টে শেয়ার করা ইমেইল ধরে।
payout_addressstringঐচ্ছিকযে PayPal ইমেইল, ওয়ালেট বা অ্যাকাউন্টে টাকা যায়। হ্যাশ করে রাখা হয়।
payout_methodstringঐচ্ছিকফ্রি টেক্সট, যেমন paypal, usdt বা giftcard।
amountnumberঐচ্ছিকক্যাশআউট বা কনভার্শনের পরিমাণ।
currencystringঐচ্ছিককারেন্সি কোড, যেমন USD। ক্যাশআউটের জন্য ডিফল্ট USD।
offer_idstringঐচ্ছিকঅফার ID, offer_click আর conversion-এর জন্য। অফারের গতি মাপতে ব্যবহৃত হয়।
offer_countrystringঐচ্ছিকযে দেশের জন্য অফার পে করে (ISO কোড, যেমন US), কনভার্শনে। অন্য দেশের ইউজার চিহ্নিত হয়।
geo_countrystringঐচ্ছিকইউজারের IP-র আপনার নিজস্ব জিওলোকেশন (ISO কোড)। আমাদেরটার সাথে না মিললে IP সম্ভবত প্রক্সি এক্সিট।
transaction_idstringঐচ্ছিককনভার্শনের নেটওয়ার্ক ট্রানজেকশন ID। ডুপ্লিকেট ধরতে ব্যবহৃত হয়।
offer_namestringঐচ্ছিকঅফারের শিরোনাম, যেমন আপনার ব্যবহারকারীরা দেখে। ড্যাশবোর্ডে ID-এর বদলে এটাই দেখায়।
click_idstringঐচ্ছিকআপনার ক্লিক ID। offer_click ও কনভার্শনে একই মান পাঠান যাতে এগুলো যুক্ত হয়।
sourcestringঐচ্ছিকইভেন্ট কোথা থেকে এসেছে, যেমন অফারওয়াল বা নেটওয়ার্কের নাম।
metaobjectঐচ্ছিকইভেন্টের সাথে সংরক্ষিত ২০টি পর্যন্ত অতিরিক্ত টেক্সট ফিল্ড (যেমন sub ID)।

রেসপন্স

রেসপন্সের কাঠামো সবসময় একই থাকে। যে ফিল্ড প্রযোজ্য নয় সেগুলো null।

  • score 0 থেকে 100। কারণগুলো এমনভাবে মেলানো হয় যাতে কয়েকটি মাঝারি সিগন্যাল যোগ হয়েও 100 পার না হয়।
  • reasons যত সিগন্যাল ট্রিগার হয়েছে সব দেখায়, সবচেয়ে শক্তিশালীটি আগে, ওয়েট, বিস্তারিত আর সরাসরি দেখানোর মতো সহজ ইংরেজি লেবেলসহ।
  • device.confidence ডিভাইসটি কতটা ইউনিক মনে হচ্ছে তা জানায়। ফিঙ্গারপ্রিন্ট স্পুফ করা যায়, তাই আমরা কখনো নিশ্চয়তার দাবি করি না।
  • linked_accounts এই অ্যাকাউন্টের সাথে ডিভাইস, পেআউট অ্যাড্রেস বা ইমেইল শেয়ার করা অন্য অ্যাকাউন্টগুলো দেখায়।
  • cashout শুধু cashout ইভেন্টে সেট হয় এবং আপনার রিভিউ কিউতে স্ট্যাটাস জানায়।

সিদ্ধান্ত ও action

decision নয়, action ফিল্ড অনুযায়ী কাজ করুন। নিচের থ্রেশহোল্ডগুলো ডিফল্ট, ড্যাশবোর্ড থেকে প্রতিটি সাইটের জন্য আলাদা করে বদলানো যায়।

সিদ্ধান্তস্কোর (ডিফল্ট)শ্যাডোতে actionenforce-এ actionকী করবেন
allow0-49allowallowস্বাভাবিকভাবে চালিয়ে যান।
review50-79allowreviewক্যাশআউট হোল্ড করুন বা অতিরিক্ত ভেরিফিকেশন চান। এটি আপনার রিভিউ কিউতে দেখা যাবে।
block80-100allowblockঅ্যাকশনটি থামান। ব্যালেন্স ফ্রিজ করুন বা সাইন আপ প্রত্যাখ্যান করুন।

শ্যাডো মোডে action সবসময় allow, তাই enforce চালুর আগেই একই কোড নিশ্চিন্তে ডিপ্লয় করতে পারেন। enforce-এ গেলে আপনার কোডে কিছুই বদলাতে হয় না।

ইভেন্টের ধরন

আপনার কাছে যে ইভেন্টগুলো আছে সেগুলো পাঠান। সাইন আপ আর ক্যাশআউট সবচেয়ে গুরুত্বপূর্ণ; কনভার্শন দিয়ে অফারের গতি চেক হয়।

ইভেন্টকখন পাঠাবেনকী ধরে
signupঅ্যাকাউন্ট তৈরি হলেমাল্টি-অ্যাকাউন্ট, বট, VPN সাইন আপ, ডিসপোজেবল ইমেইল
loginসফল লগইনের পরঅ্যাকাউন্ট শেয়ারিং, দেশ বদল, নতুন ডিভাইস
offer_clickইউজার একটি অফার খুললেঅফারের গতি মাপার ঘড়ি চালু করে
conversionofferwall বা নেটওয়ার্ক থেকে postback এলেঅতি দ্রুত শেষ হওয়া অফার, ডুপ্লিকেট ট্রানজেকশন, কনভার্শনের ঝড়
cashoutইউজার উইথড্র রিকোয়েস্ট করলেশেয়ার করা পেআউট অ্যাড্রেস, ক্যাশআউট ভেলোসিটি, নতুন অ্যাকাউন্টের ক্যাশআউট
customআর যা কিছু স্কোর করাতে চানডিভাইস ও নেটওয়ার্ক সিগন্যাল

অফারওয়াল ও পোস্টব্যাক

অফারওয়াল কনভার্শন পোস্টব্যাকের মাধ্যমে আসে, সার্ভার থেকে সার্ভারে, ব্রাউজার ছাড়া। CashoutGuard প্রতিটি কনভার্শনকে যে ক্লিক থেকে শুরু হয়েছে তার সাথে যুক্ত করে, তাই সেই ক্লিকের ডিভাইস ও নেটওয়ার্ক দিয়ে স্কোর হয়।

১. ব্যবহারকারী যখন অফার খোলে

ব্রাউজারে কালেক্ট করুন এবং অফার ও আপনার ক্লিক ID সহ offer_click পাঠান।

২. পোস্টব্যাক এলে

আপনার পোস্টব্যাক হ্যান্ডলার থেকে একই account_id ও click_id দিয়ে conversion পাঠান। request_id লাগবে না। অফারওয়াল ব্যবহারকারীর IP দিলে সেটাও পাঠান।

কনভার্শন যাচাই করা হয়: অফারের জন্য খুব দ্রুত সম্পন্ন, ক্লিক ছাড়া কনভার্শন, ক্লিক ও কনভার্শন ভিন্ন দেশ থেকে, অ্যাকাউন্টের স্বাভাবিক দিনের চেয়ে অনেক বেশি আয়, এবং ডুপ্লিকেট ট্রানজ্যাকশন ID।

অফারওয়াল নেটওয়ার্ক

অনেক পাবলিশারসহ নেটওয়ার্ক চালালে পাবলিশারসহ অ্যাকাউন্ট ID পাঠান এবং Sites-এ "অফারওয়াল নেটওয়ার্ক মোড" চালু করুন। তখন অ্যাকাউন্ট শুধু একই পাবলিশারের মধ্যে যুক্ত হয়, কারণ একজন মানুষের একাধিক পাবলিশারের সাইট ব্যবহার করা স্বাভাবিক। ফরম্যাট: publisher_id:user_id

অফার ক্যাটালগ

POST /v1/offers আপনার অফারের নাম পাঠায় (প্রতি কলে ১,০০০ পর্যন্ত)। পুরনো ও নতুন ইভেন্ট আসল নাম দেখাবে, যদিও তাতে শুধু ID থাকে।

রিজন কোড

এই কোডগুলো reasons[].code-এ আসে। মডারেটরদের টেক্সটটি দেখান; আপনার লজিকে কোডটি ব্যবহার করুন।

কোডঅর্থগ্রুপওয়েট
ip_torTor এক্সিট নোডনেটওয়ার্ক60
ip_vpnVPN কানেকশননেটওয়ার্ক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_relayiCloud 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_mismatchIP-এর থেকে ভিন্ন দেশের ফোননেটওয়ার্ক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_voipVoIP বা ভার্চুয়াল নম্বরঅ্যাকাউন্ট40
phone_invalidঅবৈধ ফোন নম্বরঅ্যাকাউন্ট30
many_devices_per_accountএক অ্যাকাউন্টে অনেক বেশি ডিভাইসঅ্যাকাউন্ট20
flagged_on_networkCashoutGuard-সুরক্ষিত অন্য ওয়েবসাইটে চিহ্নিতঅ্যাকাউন্ট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-এর দুটি সিগন্যাল দেয় 64, 80 নয়। ব্লকলিস্টে মিললে সবসময় 100।

Webhooks

ড্যাশবোর্ডে একটি ওয়েবহুক URL সেট করুন। block স্কোর পাওয়া প্রতিটি ইভেন্টে (event.blocked), কোনো অ্যাকাউন্ট block হলে (account.blocked) এবং আপনার টিম ক্যাশআউটের সিদ্ধান্ত নিলে (cashout.decided) আমরা POST পাঠাই। যে টাইপ ব্যবহার করেন না সেগুলো উপেক্ষা করুন।

প্রতিটি রিকোয়েস্ট আপনার webhook সিক্রেট দিয়ে সাইন করা। raw বডির 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 স্কোর করার পরে কনভার্শনের কী হয়েছে তা জানায়: offerwall বা বিজ্ঞাপনদাতা রিভার্স করেছে (chargeback) নাকি বৈধ। আমরা আপনার id মিলিয়ে Accuracy পেজে আপনার ট্রাফিকে ইঞ্জিন মাপি।

কোড ছাড়াই: Accuracy পেজে আপনার offerwall-এর মাসিক রিভার্সাল এক্সপোর্ট (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: ওয়ার্ডপ্রেস প্লাগইন: প্রতিটি পেজে ব্রাউজার স্ক্রিপ্ট, সাইনআপ ও লগইনের স্কোর, এবং ক্যাশআউট, অফারওয়াল কনভার্শন ও রিভার্সালের জন্য হুক।

এরর ও লিমিট

HTTPবডিঅর্থ
401missing_or_invalid_secret_keyসিক্রেট কী নেই, ভুল বা বাতিল করা হয়েছে। উত্তরে কারণ "reason"-এ (missing, public_key, unknown_secret, placeholder, malformed) এবং সমাধান "hint"-এ থাকে।
404not_foundঅ্যাকাউন্ট পাওয়া যায়নি (অ্যাকাউন্ট এন্ডপয়েন্ট)।
422{ "message", "errors" }বডি সঠিক নয়। errors-এ প্রতিটি ফিল্ড দেখানো থাকে।
429Too Many Requestsরেট লিমিটে পৌঁছে গেছেন। সার্ভার API প্রতি সাইটে মিনিটে 3,000 রিকোয়েস্ট অনুমতি দেয়।
401 · agent.jsunknown_public_keydata-key কোনো সাইটের পাবলিক কী নয়। Install থেকে pk_live_... আবার কপি করুন।
403 · agent.jsorigin_not_allowedপেজের ডোমেইন সাইটের allowed origins-এ নেই। Sites-এ যোগ করুন বা তালিকা ফাঁকা রাখুন। localhost সবসময় কাজ করে। agent.js ব্রাউজার কনসোলেও এটি জানায়। অ্যাপের WebView "null" অরিজিন পাঠায়: এগুলো গ্রহণ করতে তালিকায় null যোগ করুন। নেটিভ Android SDK-এর কিছু লাগে না।
403account_suspendedঅ্যাকাউন্ট স্থগিত, সাধারণত বকেয়া ইনভয়েসের কারণে। Billing দেখুন।
503temporarily_unavailableআমাদের দিকে সংক্ষিপ্ত সমস্যা। অ্যাকশনটি হতে দিন এবং পরে আবার চেষ্টা করুন।

Fail open: কল টাইমআউট বা এরর হলে অ্যাকশনটি allow করুন এবং লগ রাখুন। আমাদের সার্ভিস ডাউন থাকলে যেন আপনার ইউজাররা আটকে না যায়।