> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Fraud Alerts

> Respond to detected fraud and report fraudulent card transactions.

Fraud monitoring flags suspicious card transactions and gives you a short window to confirm or decline with the cardholder. You can also report fraud against a past transaction yourself. Confirming or reporting always blocks the card; declining or letting a detection expire leaves it alone.

Subscribe to fraud alert webhooks for the alert lifecycle, and to [`CARD_STATUS_UPDATED`](/api-reference/card-status-updated) for the block. Card state lives on that stream, not on the fraud alert resource.

***

## Alert lifecycle

| Status      | Meaning                                                                                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PENDING`   | Detected by fraud monitoring. Confirm or decline before `respondableUntil`.                                                                                          |
| `CONFIRMED` | Fraud confirmed. The card is blocked.                                                                                                                                |
| `DECLINED`  | Cardholder said the transaction was legitimate. The card stays active.                                                                                               |
| `EXPIRED`   | No response within the 72-hour window. The card stays active. You may still file a [manual report](#report-fraud-manually) while `reportableUntil` is in the future. |

| Origin     | Meaning                                                          |
| ---------- | ---------------------------------------------------------------- |
| `DETECTED` | Raised by fraud monitoring. Starts as `PENDING`.                 |
| `REPORTED` | Filed by you against a past transaction. Created as `CONFIRMED`. |

```mermaid theme={null}
flowchart LR
  Detect["Detected"] --> Pending["PENDING"]
  Pending -->|confirm| Confirmed["CONFIRMED"]
  Pending -->|decline| Declined["DECLINED"]
  Pending -->|no response in 72h| Expired["EXPIRED"]
  Expired -->|manual report| Confirmed
  Report["Manual report"] --> Confirmed
```

Detection alone does **not** block the card. Only confirm and manual report do.

***

## Deadlines

| Deadline                    | Field                | Applies to                                                                                                                |
| --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Respond to a detected alert | `respondableUntil`   | Always present. 72 hours from when the alert was raised.                                                                  |
| Report after expiry         | `reportableUntil`    | Set only when `status` is `EXPIRED`. Null otherwise.                                                                      |
| First-time manual report    | Enforced server-side | 180 days from the transaction date. Optionally tightened to 30 days from `cardholderNotifiedAt` when you send that field. |

Past `respondableUntil`, [Respond to alert](/api-reference/fraud-alerts/respond-to-alert) returns `FRAUD_RESPONSE_WINDOW_EXPIRED`. Use [Report fraud](/api-reference/fraud-alerts/report-fraud) instead while the reporting window is still open.

***

## Respond to a detected alert

<Steps>
  <Step title="Subscribe to the webhooks">
    Listen for [`CARD_FRAUD_ALERT_CREATED`](/api-reference/card-fraud-alert-created). When `origin` is `DETECTED` and `status` is `PENDING`, contact the cardholder before the deadline on `respondableUntil`.
  </Step>

  <Step title="Confirm or decline">
    Call [Respond to alert](/api-reference/fraud-alerts/respond-to-alert). Confirming an alert requires you to pass a [fraud type](#fraud-types).
  </Step>

  <Step title="Handle the outcome">
    You receive [`CARD_FRAUD_ALERT_STATUS_UPDATED`](/api-reference/card-fraud-alert-status-updated) with the new status.

    On confirm, also listen for [`CARD_STATUS_UPDATED`](/api-reference/card-status-updated). The card moves to `BLOCKED` with `blockReason.type: FRAUD_ALERT_CONFIRMED`.
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
  participant Reap
  participant Backend as Your backend
  participant Cardholder

  Reap->>Backend: CARD_FRAUD_ALERT_CREATED
  Backend->>Cardholder: Verify the transaction
  Cardholder-->>Backend: Confirmed / declined
  Backend->>Reap: POST /fraud-alerts/:id/respond
  Reap->>Backend: CARD_FRAUD_ALERT_STATUS_UPDATED
  Note over Reap,Backend: On confirm only
  Reap->>Backend: CARD_STATUS_UPDATED (BLOCKED, FRAUD_ALERT_CONFIRMED)
```

<Warning>
  If you miss the 72-hour window, the alert becomes `EXPIRED` and the card stays active. Check `reportableUntil` on the alert. While that timestamp is still in the future, file a [manual report](#report-fraud-manually) on the same transaction to confirm fraud and block the card.
</Warning>

***

## Report fraud manually

Use this when the cardholder later flags a transaction, or when a detected alert expired and `reportableUntil` is still ahead of now.

<Steps>
  <Step title="Identify the transaction">
    Take the card transaction ID from your records.
  </Step>

  <Step title="File the report">
    Call [Report fraud](/api-reference/fraud-alerts/report-fraud) with `transactionId`, `type`, and optionally `cardholderNotifiedAt`.

    The report always confirms fraud and blocks the card. If a pending detected alert already exists for that transaction and is still inside the response window, the call confirms it instead of creating a second alert (transaction and alert are 1:1).
  </Step>

  <Step title="Handle the block">
    You receive [`CARD_FRAUD_ALERT_CREATED`](/api-reference/card-fraud-alert-created) or [`CARD_FRAUD_ALERT_STATUS_UPDATED`](/api-reference/card-fraud-alert-status-updated) with `status: CONFIRMED`, plus [`CARD_STATUS_UPDATED`](/api-reference/card-status-updated) with `blockReason.type: FRAUD_ALERT_CONFIRMED`.
  </Step>
</Steps>

<Note>
  When the cardholder notified you of the suspected fraud, pass `cardholderNotifiedAt`. The reporting window becomes the earlier of 180 days from the transaction and 30 days from that notification. When omitted, only the 180-day transaction window is enforced server-side; the 30-day notification limb remains your obligation.
</Note>

***

## Fraud types

Required when confirming a detected alert or filing a manual report.

| Value                   | Use when                                                                       |
| ----------------------- | ------------------------------------------------------------------------------ |
| `CARD_LOST`             | The cardholder lost the card.                                                  |
| `CARD_STOLEN`           | The card was stolen.                                                           |
| `ACCOUNT_NUMBER_MISUSE` | The cardholder still has the card, but the account number was used without it. |
| `OTHER`                 | Confirmed fraud that none of the above classify.                               |