Skip to main content
Early Fraud Warnings (EFWs) are real-time alerts issued by card networks when a cardholder reports potential fraud on a transaction. They arrive before a formal dispute (chargeback) is filed, giving you a window to proactively refund a suspicious charge and potentially avoid a chargeback entirely.

Table of contents


Overview

There is no REST API to list or retrieve EFWs. All EFW data is delivered exclusively through webhook events. Subscribe to radar.early_fraud_warning.created and radar.early_fraud_warning.updated in your webhook configuration.

Key facts

  • EFWs are read-only, Flex does not expose an API to query or acknowledge them.
  • An EFW does not mean a dispute has been filed. It’s a signal that the cardholder may have flagged the transaction.
  • A single charge may receive multiple EFWs (one created, then updated as circumstances change).
  • actionable: true means the charge has not yet been refunded or disputed, act now.
  • actionable: false means the charge has already been fully refunded or a dispute has been filed. No action needed.

How EFWs differ from disputes


The EarlyFraudWarning object

This is the object delivered inside every radar.early_fraud_warning.* webhook event.

Field reference


Fraud type reference

unauthorized_use_of_card and card_never_received are the most common in ecommerce.

Webhook events

radar.early_fraud_warning.created

Fired when Flex receives a new early fraud warning for one of your charges.

radar.early_fraud_warning.updated

Fired when an existing EFW changes, most commonly when actionable transitions from true to false (because the charge was refunded or a formal dispute was filed).

Webhook signature verification

All Flex webhooks include a flex-signature header. Verify it using your webhook signing secret from the Flex Dashboard. See the Webhooks documentation for signature verification details.

Idempotency

EFWs are upserted on early_fraud_warning_id, receiving the same event twice will not create duplicate records. Your webhook handler should be idempotent: processing the same event_id twice should have no side-effects.
When you receive radar.early_fraud_warning.created with actionable: true:

1. Assess the risk

Check the fraud_type and correlate the charge_id or client_reference_id to the order in your system.
  • Is this order already shipped? Shipped orders are harder to recover.
  • Is the fraud_type high-risk (card_never_received, made_with_stolen_card)? These have a higher probability of becoming a formal chargeback.

2. Decide: refund or wait

3. Issue a refund (if decided)

Use the Flex Refunds API to issue a full or partial refund for the charge_id in the EFW. Once refunded, the EFW will be updated to actionable: false and you’ll receive a radar.early_fraud_warning.updated event.

4. Track your chargeback rate

A high chargeback rate (typically >1%) can result in penalties from card networks. EFWs are an early signal to detect patterns, monitor fraud_type across EFWs to identify systemic fraud patterns in your customer base.

End-to-end testing guide

Note: EFW events can’t be triggered by test card payments alone, card networks don’t issue EFWs in response to standard test transactions. Use the synthetic webhook method below to simulate the full flow end-to-end against your local Flex server.

Prerequisites

  • Flex API key and webhook signing secret (from your Flex Dashboard)
  • Your webhook endpoint URL (must be reachable. Use ngrok for local development)
  • Python 3 or any HMAC-SHA256 capable language

Step 1, Register a webhook endpoint

In your Flex Dashboard, register your endpoint URL and subscribe to:
  • radar.early_fraud_warning.created
  • radar.early_fraud_warning.updated

Step 2. Create a charge

Create a checkout session and complete a payment. Note the charge_id (fch_...) and payment_intent_id (fpi_...) from the checkout session response. Optionally include a client_reference_id in your checkout session request to verify it’s propagated to EFW events:

Step 3. Send a synthetic EFW event

Use the script below to generate a correctly signed event and POST it to your local Flex server. Flex will process it and forward the resulting radar.early_fraud_warning.created event to your registered webhook endpoint.
Where to find the charge and payment intent IDs: After completing a payment in Flex Checkout, look at the checkout_session response. Its payment_intent field contains the payment intent ID (pi_...). The corresponding charge ID (ch_...) can be retrieved by fetching the payment intent from the Flex API.

Step 4, Verify the event arrives at your endpoint

Your webhook handler should receive:
Verify:
  • early_fraud_warning_id has fefw_ prefix (Flex ID)
  • charge_id and payment_intent_id are Flex IDs (fch_, fpi_)
  • client_reference_id matches what you set on the checkout session (if applicable)
  • actionable: true

Step 5, Test the updated event

Re-send with actionable: false and type: "radar.early_fraud_warning.updated", keeping the same id in data.object:
Verify:
  • Your endpoint receives radar.early_fraud_warning.updated
  • The same early_fraud_warning_id is in the event (upserted, not duplicated)
  • actionable is now false

Step 6, test idempotency

Resend the same radar.early_fraud_warning.created event (same id in data.object, e.g. efw_synthetic_001, with a different event timestamp). Verify your handler processes it without creating a duplicate record.

Step 7, Verify client_reference_id propagation

If you created the checkout session with a client_reference_id:
  • Confirm it appears in the object of the EFW event
  • This lets you correlate the EFW directly to your internal order without any additional lookups

Checklist