Dokumentation

Ein Script im Browser, ein API-Aufruf von deinem Server. Alles, was du für den Livegang brauchst, auf einer Seite.

Schnellstart

Du brauchst deinen Public Key (pk_...) für den Browser und deinen Secret Key (sk_...) für deinen Server. Beide findest du im Dashboard unter Sites und Keys.

1. Script einbinden

Setz diesen Tag auf die Seiten, auf denen Nutzer sich registrieren, einloggen, Angebote klicken oder einen Cashout anfordern. Er initialisiert sich selbst über data-key

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

2. request_id erfassen und an deinen Server senden

Ruf collect() im entscheidenden Moment mit dem Event-Namen auf. Das Ergebnis ist { request_id, visitor_id }

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

collect() wird nie rejected. Bei einem Fehler (blockiert, offline, Timeout) liefert es request_id: null und einen Fehlertext. Schick das Formular trotzdem ab und lass deinen Server entscheiden.

3. Entscheidung von deinem Server abfragen

Sende das Event per POST an /v1/evaluate, mit deinem Secret Key im Header Authorization: Bearer sk_live_...

Pack den Secret Key nie in Browser-Code oder eine mobile App. Nur dein Server darf /v1/evaluate aufrufen.

Evaluate-Request

POST https://cashoutguard.com/v1/evaluate bewertet ein Event für ein Konto, verknüpft es mit Gerät, Netzwerk und Auszahlungsadresse und liefert eine Entscheidung zurück. Sende JSON.

Response

Die Response hat immer dieselbe Struktur. Felder, die nicht zutreffen, sind null.

• score liegt zwischen 0 und 100. Gründe werden kombiniert, sodass sich mehrere mittlere Signale summieren, ohne 100 zu überschreiten.
• reasons listet jedes ausgelöste Signal auf, das stärkste zuerst, mit Gewicht, Details und einem verständlichen englischen Label, das du direkt anzeigen kannst.
• device.confidence gibt an, wie eindeutig das Gerät wirkt. Fingerprints lassen sich fälschen, deshalb behaupten wir nie absolute Sicherheit.
• linked_accounts listet andere Konten auf, die sich Gerät, Auszahlungsadresse oder E-Mail mit diesem Konto teilen.
• cashout ist nur bei cashout-Events gesetzt und zeigt den Status in deiner Prüfliste.

Entscheidungen und Aktionen

Reagiere auf das Feld action, nicht auf decision. Die Schwellenwerte unten sind Standardwerte und lassen sich im Dashboard pro Site ändern.

Im Shadow-Modus ist action immer allow, du kannst denselben Code also gefahrlos ausliefern, bevor du Enforce aktivierst. Beim Umschalten auf Enforce ändert sich nichts an deinem Code.

Event-Typen

Sende die Events, die du hast. Signup und Cashout sind am wichtigsten; Conversions liefern die Daten für die Prüfung des Angebotstempos.

Offerwalls und Postbacks

Offerwall-Conversions kommen per Postback, Server zu Server, ohne Browser. CashoutGuard verknüpft jede Conversion mit dem Klick, der sie ausgelöst hat, und bewertet sie mit Gerät und Netzwerk dieses Klicks.

1. Wenn der Nutzer ein Angebot öffnet

Sammle im Browser und sende ein offer_click mit dem Angebot und deiner Klick-ID.

2. Wenn der Postback eintrifft

Sende aus deinem Postback-Handler eine conversion mit derselben account_id und click_id. Eine request_id ist nicht nötig. Gib die IP des Nutzers mit, falls die Offerwall sie liefert.

Conversions werden geprüft auf: zu schnell für das Angebot, Conversion ohne Klick, Klick und Conversion aus verschiedenen Ländern, Einnahmen weit über dem üblichen Tag des Kontos und doppelte Transaktions-IDs.

Offerwall-Netzwerke

Betreibst du ein Netzwerk mit vielen Publishern, sende Konto-IDs mit dem Publisher und aktiviere den "Offerwall-Netzwerk-Modus" unter Websites. Dann werden Konten nur innerhalb desselben Publishers verknüpft, weil es normal ist, dass eine Person mehrere Seiten deiner Publisher nutzt. Format: publisher_id:user_id

Angebotskatalog

POST /v1/offers sendet deine Angebotsnamen (bis zu 1.000 pro Aufruf). Vergangene und künftige Ereignisse zeigen dann den echten Namen, auch wenn sie nur die ID enthalten.

Reason-Codes

Diese Codes erscheinen in reasons[].code. Zeig deinen Moderatoren den Text; nutze den Code in deiner Logik.

Gewichte werden per Noisy-OR kombiniert: score = 100 x (1 - Produkt von (1 - weight/100)). Zwei Signale mit 40 ergeben 64, nicht 80. Ein Treffer auf der Blocklist ergibt immer 100.

Webhooks

Legen Sie im Dashboard eine Webhook-URL fest. Wir senden einen POST für jedes mit block bewertete Ereignis (event.blocked), wenn ein Konto auf block wechselt (account.blocked) und wenn Ihr Team über eine Auszahlung entscheidet (cashout.decided). Ignorieren Sie Typen, die Sie nicht nutzen.

Jeder Request wird mit deinem Webhook-Secret signiert. Der Hex-HMAC-SHA256 des Raw-Bodys steht im Header X-CashoutGuard-Signature

Antworte mit einem beliebigen 2xx-Status. Fehlgeschlagene Zustellungen werden bis zu 5 Mal wiederholt: nach 10 Sekunden, 1 Minute, 5 Minuten und 15 Minuten.

Kontostatus

GET /v1/accounts/{account_id} liefert die aktuelle Risikoeinschätzung eines Kontos, ohne ein Event anzulegen.

POST /v1/accounts/{account_id}/status erlaubt deinen eigenen Moderationstools, den Status eines Kontos zu ändern.

• active: Normales Scoring.
• allowlisted: Scores bleiben unter der Prüfschwelle. Für vertrauenswürdige Nutzer und Mitarbeiter.
• blocked: Jedes Event liefert block mit Score 100.

Rückbuchungen & Genauigkeit

POST /v1/outcomes meldet, was mit Conversions nach unserer Bewertung passiert ist: vom Offerwall oder Werbetreibenden zurückgebucht (Chargeback) oder als gültig bestätigt. Wir ordnen Ihre IDs zu und messen die Engine auf Ihrem eigenen Traffic auf der Seite Genauigkeit.

Ohne Code: Laden Sie den monatlichen Rückbuchungs-Export Ihrer Offerwalls (CSV oder Excel) auf der Seite Genauigkeit hoch. Die ID-Spalte finden wir automatisch.

PHP, Node.js, Python, Android

Kein SDK nötig. Ein einfacher HTTP-Aufruf mit kurzem Timeout reicht. Komplettes Cashout-Beispiel:

• cashoutguard.php: PHP 7.4+, eine Datei, ohne Composer. Einbinden und fertig.
• composer require cashoutguard/cashoutguard-php: derselbe PHP-Client mit README für Ihren vendor-Ordner.
• npm install @cashoutguard/node: Node 18+, mit TypeScript-Typen.
• cashoutguard-wordpress.zip: WordPress-Plugin: das Browser-Skript auf jeder Seite, bewertete Registrierungen und Logins sowie Hooks für Auszahlungen, Offerwall-Conversions und Stornos.

Fehler und Limits

Fail open: Wenn der Aufruf in einen Timeout läuft oder fehlschlägt, lass die Aktion zu und protokolliere sie. Unser Ausfall darf nie deine Nutzer aufhalten.