Skip to main content
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 for the block. Card state lives on that stream, not on the fraud alert resource. Confirming fraud blocks the card. It does not recover the money. To challenge the charge itself, file a dispute against the same transaction. The two are independent and neither requires the other.

​
Alert lifecycle

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

​
Deadlines

Past respondableUntil, Respond to alert returns FRAUD_RESPONSE_WINDOW_EXPIRED. Use Report fraud instead while the reporting window is still open.
In sandbox, simulated fraud detections can expire after about 5 minutes. You still get CARD_FRAUD_ALERT_STATUS_UPDATED with status: EXPIRED. Production uses the 72-hour respondableUntil window; do not treat sandbox expiry timing as the live contract.

​
Respond to a detected alert

1

Subscribe to the webhooks

Listen for CARD_FRAUD_ALERT_CREATED. When origin is DETECTED and status is PENDING, contact the cardholder before the deadline on respondableUntil.
2

Confirm or decline

Call Respond to alert. Confirming an alert requires you to pass a fraud type.
3

Handle the outcome

You receive CARD_FRAUD_ALERT_STATUS_UPDATED with the new status.On confirm, also listen for CARD_STATUS_UPDATED. The card moves to BLOCKED with blockReason.type: FRAUD_ALERT_CONFIRMED.
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 on the same transaction to confirm fraud and block the card.

​
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.
1

Identify the transaction

Take the card transaction ID from your records.
2

File the report

Call 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).
3

Handle the block

You receive CARD_FRAUD_ALERT_CREATED or CARD_FRAUD_ALERT_STATUS_UPDATED with status: CONFIRMED, plus CARD_STATUS_UPDATED with blockReason.type: FRAUD_ALERT_CONFIRMED.

​
After a confirmed fraud alert

A fraud block reports blockLiftable: true, so Unblock will lift it. Prefer deleting the card and issuing a replacement instead. The card number is compromised, and unblocking returns that same number to circulation. Unblock is there for the case where the cardholder confirmed the alert by mistake.
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.

​
Fraud types

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