Documentation

Un script dans le navigateur, un appel API depuis votre serveur. Tout ce qu'il faut pour passer en production, sur une seule page.

Démarrage rapide

Il vous faut votre clé publique (pk_...) pour le navigateur et votre clé secrète (sk_...) pour votre serveur. Les deux se trouvent dans le tableau de bord, rubrique Sites et clés.

1. Ajoutez le script

Placez cette balise sur les pages où les utilisateurs s'inscrivent, se connectent, cliquent sur des offres ou demandent un retrait. Il s'initialise automatiquement à partir de data-key

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

2. Collectez et envoyez le request_id à votre serveur

Appelez collect() au moment qui compte, avec le nom de l'événement. La promesse se résout en { request_id, visitor_id }

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

collect() n'est jamais rejetée. En cas d'échec (blocage, hors ligne, délai dépassé), elle se résout avec request_id: null et une chaîne d'erreur. Envoyez quand même le formulaire et laissez votre serveur décider.

3. Demandez une décision depuis votre serveur

Envoyez l'événement en POST à /v1/evaluate avec votre clé secrète dans l'en-tête Authorization: Bearer sk_live_...

Ne mettez jamais la clé secrète dans du code navigateur ou une application mobile. Seul votre serveur doit appeler /v1/evaluate.

Requête evaluate

POST https://cashoutguard.com/v1/evaluate score un événement pour un compte, le relie à son appareil, son réseau et son adresse de paiement, et renvoie une décision. Envoyez du JSON.

Réponse

La réponse a toujours la même structure. Les champs non applicables valent null.

• score va de 0 à 100. Les raisons se combinent : plusieurs signaux moyens s'additionnent sans jamais dépasser 100.
• reasons liste chaque signal déclenché, du plus fort au plus faible, avec son poids, ses détails et un libellé en anglais clair à afficher tel quel.
• device.confidence indique à quel point l'appareil semble unique. Les empreintes peuvent être falsifiées, nous ne prétendons donc jamais à la certitude.
• linked_accounts liste les autres comptes qui partagent un appareil, une adresse de paiement ou un e-mail avec celui-ci.
• cashout n'est renseigné que pour les événements cashout et indique le statut dans votre file de validation.

Décisions et actions

Basez-vous sur le champ action, pas sur decision. Les seuils ci-dessous sont les valeurs par défaut et peuvent être modifiés par site dans le tableau de bord.

En mode shadow, action vaut toujours allow : le même code peut donc être déployé sans risque avant de passer en enforce. Au moment du passage en enforce, rien ne change dans votre code.

Types d'événements

Envoyez les événements dont vous disposez. Signup et cashout sont les plus importants ; les conversions alimentent les contrôles de vitesse des offres.

Offerwalls et postbacks

Les conversions d'offerwall arrivent par postback, de serveur à serveur, sans navigateur. CashoutGuard relie chaque conversion au clic qui l'a déclenchée : elle est notée avec l'appareil et le réseau de ce clic.

1. Quand l'utilisateur ouvre une offre

Collectez dans le navigateur et envoyez un offer_click avec l'offre et votre id de clic.

2. Quand le postback arrive

Envoyez une conversion depuis votre gestionnaire de postback avec le même account_id et click_id. Pas besoin de request_id. Transmettez l'IP de l'utilisateur si l'offerwall la fournit.

Les conversions sont vérifiées : terminée trop vite pour l'offre, conversion sans clic, clic et conversion depuis des pays différents, gains bien au-dessus de la journée habituelle du compte et ids de transaction en double.

Réseaux offerwall

Si vous gérez un réseau avec de nombreux éditeurs, envoyez des ids de compte incluant l'éditeur et activez le « Mode réseau offerwall » dans Sites. Les comptes ne sont alors liés qu'au sein du même éditeur, car il est normal qu'une personne utilise plusieurs sites de vos éditeurs. Format : publisher_id:user_id

Catalogue d'offres

POST /v1/offers envoie les noms de vos offres (jusqu'à 1 000 par appel). Les événements passés et futurs affichent alors le vrai nom même s'ils ne portent que l'id.

Codes de raison

Ces codes apparaissent dans reasons[].code. Montrez le texte à vos modérateurs ; utilisez le code dans votre logique.

Les poids sont combinés par un OU bruité (noisy-OR) : score = 100 x (1 - produit de (1 - poids/100)). Deux signaux de 40 donnent 64, et non 80. Une correspondance avec la liste noire donne toujours 100.

Webhooks

Définissez une URL de webhook dans le tableau de bord. Nous envoyons un POST pour chaque événement noté block (event.blocked), quand un compte passe à block (account.blocked) et quand votre équipe décide d’un retrait (cashout.decided). Ignorez les types que vous n’utilisez pas.

Chaque requête est signée avec votre secret de webhook. Le HMAC-SHA256 hexadécimal du corps brut figure dans l'en-tête X-CashoutGuard-Signature

Répondez avec n'importe quel statut 2xx. Les envois échoués sont retentés jusqu'à 5 fois : après 10 secondes, 1 minute, 5 minutes et 15 minutes.

Statut des comptes

GET /v1/accounts/{account_id} renvoie la vue de risque actuelle d'un compte sans créer d'événement.

POST /v1/accounts/{account_id}/status permet à vos propres outils de modération de modifier le statut d'un compte.

• active: Scoring normal.
• allowlisted: Les scores sont plafonnés sous le seuil de vérification. Pour les utilisateurs de confiance et l'équipe.
• blocked: Chaque événement renvoie block avec un score de 100.

Annulations et précision

POST /v1/outcomes indique ce qu'il est advenu des conversions après notre score : annulées par l'offerwall ou l'annonceur (chargeback) ou confirmées valides. Nous rapprochons vos identifiants et mesurons le moteur sur votre propre trafic dans la page Précision.

Sans code : importez l'export mensuel des annulations de vos offerwalls (CSV ou Excel) dans la page Précision. Nous trouvons la colonne d'identifiants automatiquement.

PHP, Node.js, Python, Android

Aucun SDK nécessaire. Un simple appel HTTP avec un délai d'expiration court suffit. Exemple complet de retrait :

• cashoutguard.php: PHP 7.4+, un seul fichier, sans Composer. Un require et c'est tout.
• composer require cashoutguard/cashoutguard-php: le même client PHP avec son README, pour votre dossier vendor.
• npm install @cashoutguard/node: Node 18+, types TypeScript inclus.
• cashoutguard-wordpress.zip: extension WordPress : le script navigateur sur toutes les pages, inscriptions et connexions évaluées, et des hooks pour les retraits, les conversions d'offerwall et les annulations.

Erreurs et limites

Fail open : si l'appel expire ou échoue, autorisez l'action et consignez-la. Ne laissez jamais une panne de notre côté bloquer vos utilisateurs.