0
# Radar
1

2
Stripe Radar provides advanced fraud prevention and risk management tools using machine learning to analyze payments and identify suspicious activity. It includes customizable rules, allow/block lists, and comprehensive fraud analytics to protect businesses from fraudulent transactions.
3

4
## Fraud Prevention
5

6
### Radar.EarlyFraudWarnings
7

8
Monitor and manage early fraud warnings from card networks:
9

10
```typescript { .api }
11
interface EarlyFraudWarning {
12
  id: string;
13
  object: 'radar.early_fraud_warning';
14
  actionable: boolean;
15
  charge: string;
16
  created: number;
17
  fraud_type: 'card_never_received' | 'fraudulent_card_application' | 'made_with_counterfeit_card' | 'made_with_lost_card' | 'made_with_stolen_card' | 'misc' | 'unauthorized_use_of_card';
18
  livemode: boolean;
19
  payment_intent?: string;
20
}
21

22
// Retrieve early fraud warning
23
const warning = await stripe.radar.earlyFraudWarnings.retrieve('issfr_123');
24

25
// List early fraud warnings
26
const warnings = await stripe.radar.earlyFraudWarnings.list({
27
  limit: 10,
28
  charge: 'ch_123'
29
});
30

31
// List warnings by creation date
32
const recentWarnings = await stripe.radar.earlyFraudWarnings.list({
33
  created: {
34
    gte: Math.floor(Date.now() / 1000) - (7 * 24 * 60 * 60) // Last 7 days
35
  }
36
});
37
```
38

39
### Radar.ValueLists
40

41
Create and manage lists of values for fraud prevention rules:
42

43
```typescript { .api }
44
interface ValueList {
45
  id: string;
46
  object: 'radar.value_list';
47
  alias: string;
48
  created: number;
49
  created_by: string;
50
  item_type: 'card_bin' | 'card_fingerprint' | 'case_sensitive_string' | 'country' | 'customer_id' | 'email' | 'ip_address' | 'sepa_debit_fingerprint' | 'string' | 'us_bank_account_fingerprint';
51
  list_items: {
52
    data: Array<{
53
      id: string;
54
      value: string;
55
      created: number;
56
      created_by: string;
57
    }>;
58
    has_more: boolean;
59
    url: string;
60
  };
61
  livemode: boolean;
62
  metadata: Record<string, string>;
63
  name: string;
64
}
65

66
// Create value list for blocked emails
67
const emailBlocklist = await stripe.radar.valueLists.create({
68
  alias: 'blocked_emails',
69
  name: 'Blocked Email Domains',
70
  item_type: 'email',
71
  metadata: {
72
    purpose: 'fraud_prevention'
73
  }
74
});
75

76
// Create IP address allowlist
77
const ipAllowlist = await stripe.radar.valueLists.create({
78
  alias: 'trusted_ips',
79
  name: 'Trusted IP Addresses',
80
  item_type: 'ip_address'
81
});
82

83
// Create country blocklist
84
const countryBlocklist = await stripe.radar.valueLists.create({
85
  alias: 'blocked_countries',
86
  name: 'High Risk Countries',
87
  item_type: 'country'
88
});
89

90
// Retrieve value list
91
const retrieved = await stripe.radar.valueLists.retrieve('rsl_123');
92

93
// Update value list
94
const updated = await stripe.radar.valueLists.update('rsl_123', {
95
  name: 'Updated Blocked Emails',
96
  metadata: {
97
    last_updated: new Date().toISOString()
98
  }
99
});
100

101
// List value lists
102
const valueLists = await stripe.radar.valueLists.list({
103
  limit: 10
104
});
105

106
// Delete value list
107
const deleted = await stripe.radar.valueLists.del('rsl_123');
108
```
109

110
### Radar.ValueListItems
111

112
Manage individual items within value lists:
113

114
```typescript { .api }
115
interface ValueListItem {
116
  id: string;
117
  object: 'radar.value_list_item';
118
  created: number;
119
  created_by: string;
120
  livemode: boolean;
121
  value: string;
122
  value_list: string;
123
}
124

125
// Add items to email blocklist
126
const blockedEmail = await stripe.radar.valueListItems.create({
127
  value_list: 'rsl_123',
128
  value: 'suspicious@example.com'
129
});
130

131
// Add multiple IPs to allowlist
132
const trustedIps = [
133
  '192.168.1.1',
134
  '10.0.0.1',
135
  '172.16.0.1'
136
];
137

138
for (const ip of trustedIps) {
139
  await stripe.radar.valueListItems.create({
140
    value_list: 'rsl_456',
141
    value: ip
142
  });
143
}
144

145
// Add country codes to blocklist
146
const blockedCountries = ['XX', 'YY'];
147
for (const country of blockedCountries) {
148
  await stripe.radar.valueListItems.create({
149
    value_list: 'rsl_789',
150
    value: country
151
  });
152
}
153

154
// Retrieve value list item
155
const item = await stripe.radar.valueListItems.retrieve('rsli_123');
156

157
// List items in value list
158
const items = await stripe.radar.valueListItems.list({
159
  value_list: 'rsl_123',
160
  limit: 100
161
});
162

163
// Delete value list item
164
const deletedItem = await stripe.radar.valueListItems.del('rsli_123');
165
```
166

167
## Fraud Analytics and Rules
168

169
### Custom Radar Rules
170

171
```typescript { .api }
172
// Example: Block payments from high-risk countries
173
// This would be configured in the Stripe Dashboard, but you can reference lists:
174

175
// Create a rule in Dashboard like:
176
// "Block if :ip_country: is in :blocked_countries:"
177
// where :blocked_countries: references your value list
178

179
// The API doesn't create rules directly, but you can manage the data that rules use
180
const highRiskCountries = await stripe.radar.valueLists.create({
181
  alias: 'high_risk_countries',
182
  name: 'High Risk Countries',
183
  item_type: 'country'
184
});
185

186
// Add countries to the list
187
const riskCountries = ['CN', 'RU', 'NG'];
188
for (const country of riskCountries) {
189
  await stripe.radar.valueListItems.create({
190
    value_list: highRiskCountries.id,
191
    value: country
192
  });
193
}
194
```
195

196
### Payment Monitoring
197

198
```typescript { .api }
199
// Monitor payment outcomes for fraud analysis
200
app.post('/webhook', (req, res) => {
201
  const event = stripe.webhooks.constructEvent(
202
    req.body,
203
    req.headers['stripe-signature'],
204
    endpointSecret
205
  );
206

207
  switch (event.type) {
208
    case 'radar.early_fraud_warning.created':
209
      const warning = event.data.object;
210
      console.log('Early fraud warning:', {
211
        charge: warning.charge,
212
        fraud_type: warning.fraud_type,
213
        actionable: warning.actionable
214
      });
215
      
216
      // Take action on high-risk warnings
217
      if (warning.actionable) {
218
        handleFraudWarning(warning);
219
      }
220
      break;
221
      
222
    case 'charge.dispute.created':
223
      const dispute = event.data.object;
224
      
225
      // Analyze dispute patterns
226
      analyzeDisputePattern(dispute);
227
      break;
228
      
229
    case 'payment_intent.payment_failed':
230
      const failedPayment = event.data.object;
231
      
232
      // Check if failure was due to fraud prevention
233
      if (failedPayment.last_payment_error?.decline_code) {
234
        logFraudPrevention(failedPayment);
235
      }
236
      break;
237
  }
238

239
  res.json({ received: true });
240
});
241

242
async function handleFraudWarning(warning: any) {
243
  // Retrieve the charge details
244
  const charge = await stripe.charges.retrieve(warning.charge);
245
  
246
  // Add customer email to watch list if needed
247
  if (charge.billing_details?.email) {
248
    await stripe.radar.valueListItems.create({
249
      value_list: 'suspicious_emails_list_id',
250
      value: charge.billing_details.email
251
    });
252
  }
253
  
254
  // Refund if appropriate
255
  if (warning.fraud_type === 'unauthorized_use_of_card') {
256
    await stripe.refunds.create({
257
      charge: warning.charge,
258
      reason: 'fraudulent'
259
    });
260
  }
261
}
262
```
263

264
### Risk Assessment Integration
265

266
```typescript { .api }
267
// Create PaymentIntent with Radar context
268
const paymentIntent = await stripe.paymentIntents.create({
269
  amount: 2000,
270
  currency: 'usd',
271
  customer: 'cus_123',
272
  payment_method_types: ['card'],
273
  metadata: {
274
    order_id: 'order_12345',
275
    user_id: 'user_789'
276
  },
277
  // Radar will automatically analyze this payment
278
  radar_options: {
279
    session: 'session_abc123' // Optional: link to checkout session
280
  }
281
});
282

283
// Check outcome after confirmation
284
const confirmedPayment = await stripe.paymentIntents.confirm(paymentIntent.id, {
285
  payment_method: 'pm_card_visa'
286
});
287

288
// Access Radar outcome
289
const outcome = confirmedPayment.charges?.data[0]?.outcome;
290
if (outcome) {
291
  console.log('Radar risk assessment:', {
292
    risk_level: outcome.risk_level, // 'normal', 'elevated', 'highest'
293
    risk_score: outcome.risk_score, // 0-100
294
    reason: outcome.reason,
295
    seller_message: outcome.seller_message
296
  });
297
}
298
```
299

300
### Advanced List Management
301

302
```typescript { .api }
303
// Create comprehensive fraud prevention lists
304
async function setupFraudPrevention() {
305
  // 1. Blocked email domains
306
  const emailBlocklist = await stripe.radar.valueLists.create({
307
    alias: 'blocked_email_domains',
308
    name: 'Blocked Email Domains',
309
    item_type: 'string'
310
  });
311
  
312
  const suspiciousDomains = [
313
    '10minutemail.com',
314
    'tempmail.org',
315
    'guerrillamail.com'
316
  ];
317
  
318
  for (const domain of suspiciousDomains) {
319
    await stripe.radar.valueListItems.create({
320
      value_list: emailBlocklist.id,
321
      value: domain
322
    });
323
  }
324
  
325
  // 2. Trusted customer IDs
326
  const trustedCustomers = await stripe.radar.valueLists.create({
327
    alias: 'trusted_customers',
328
    name: 'Trusted Customers',
329
    item_type: 'customer_id'
330
  });
331
  
332
  // 3. Blocked card BINs
333
  const blockedBins = await stripe.radar.valueLists.create({
334
    alias: 'blocked_card_bins',
335
    name: 'Blocked Card BINs',
336
    item_type: 'card_bin'
337
  });
338
  
339
  return {
340
    emailBlocklist,
341
    trustedCustomers,
342
    blockedBins
343
  };
344
}
345

346
// Maintenance: Clean up old entries
347
async function cleanupValueLists() {
348
  const valueLists = await stripe.radar.valueLists.list({ limit: 100 });
349
  
350
  for (const list of valueLists.data) {
351
    const items = await stripe.radar.valueListItems.list({
352
      value_list: list.id,
353
      limit: 100
354
    });
355
    
356
    // Remove outdated items (example: older than 6 months)
357
    const sixMonthsAgo = Math.floor(Date.now() / 1000) - (6 * 30 * 24 * 60 * 60);
358
    
359
    for (const item of items.data) {
360
      if (item.created < sixMonthsAgo) {
361
        await stripe.radar.valueListItems.del(item.id);
362
      }
363
    }
364
  }
365
}
366
```
367

368
Stripe Radar provides comprehensive fraud protection through machine learning-based risk assessment, customizable rules, and detailed analytics, helping businesses reduce chargebacks and fraudulent transactions while maintaining a smooth experience for legitimate customers.