Fraud
What Vouch detects, what the review queue does with it, and how a refund takes a reward back.
Any programme that pays people attracts people who want to be paid without doing the work. Vouch flags the obvious cases, holds the doubtful ones for you, and never silently pays a referral it suspects.
What is detected
| Flag | Raised when |
|---|---|
self_referral_device | The invitee's device is the inviter's device. |
self_referral_user | The invitee is the inviter. |
self_referral_fingerprint | Both sides share a device fingerprint, so they are probably the same person. |
invite_velocity | One inviter is sending invitations faster than the programme allows. |
qualify_velocity | One inviter's referrals are qualifying faster than the programme allows. |
device_verdict_failed | Device security says the invitee's device is not genuine. |
Set the thresholds per programme:
{
"fraud_policy": {
"block_self_referral": true,
"max_invites_per_hour": 20,
"max_qualified_per_day": 50,
"exclude_failed_device_verdict": true
}
}exclude_failed_device_verdict only acts on devices with a recorded failing verdict. A device with
no verdict at all passes, so switching it on cannot quietly discard referrals from an app that has
not adopted device security.
The review queue
review_policy decides what reaches you.
| Policy | Sends to review |
|---|---|
none | Nothing. Flags are recorded on the referral but rewards are issued. |
suspicious_only | Only flagged referrals. This is the usual choice. |
all | Every referral, before any reward is issued. |
A referral in review sits in under_review and its rewards sit in held. Nothing is paid until you
decide.
| Decision | Effect |
|---|---|
approved | The referral qualifies and its held rewards are granted. |
rejected | The referral is rejected and its held rewards are reversed. |
fraud | The same as rejected, and recorded as confirmed abuse. |
curl -X POST https://api.vouch.dev/v1/referral-reviews/rrv_123/decide \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"decision":"approved","note":"Known customer, different household"}'Each queue item arrives with the referral and the rewards being held, so you can decide without looking anything up.
A self-referral is never silently qualified, whatever your review policy. It is recorded and held, and the attempt is visible.
Clawbacks
If a purchase that qualified a referral is refunded, the reward should not stand. Report the refund as a conversion and Vouch reverses it.
curl -X POST https://api.vouch.dev/v1/conversions \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{
"app_id": "app_123",
"external_user_id": "user_456",
"type": "refund",
"amount_minor": 4900,
"currency": "GBP",
"source": "api",
"source_transaction_id": "re_1234567890"
}'Inside the programme's clawback_window_days, 30 by default:
- every reward on that referral moves to
reversed, - the referral moves to
clawed_back, - a webhook fires so you can undo your side, since Vouch cannot take back credits inside your app.
Clawbacks are idempotent. Reporting the same refund twice reverses once.
Reversing by hand
Sometimes you know something the rules do not.
curl -X POST https://api.vouch.dev/v1/rewards/rwd_123/reverse \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"reason":"Chargeback outside the clawback window"}'The reason is stored on the reward and appears in the audit log.