Retrieve fraud reports via API

Use the SAFE/TC40 API to retrieve reports of transactions flagged as fraudulent by MasterCard or Visa. These reports are accessible through the merchant console under Risk Management, or programmatically via the API.

You can retrieve fraud report data:

By ARN or original transaction unique ID
As a full list of reports per transaction
For a specified date range (paginated)

About SAFE/TC40 fraud reports

SAFE (MasterCard) and TC40 (Visa) reports capture fraud events reported by issuers. These include situations like stolen cards, account takeovers, or counterfeit use. The reports help issuers, acquirers, and merchants identify and mitigate fraudulent activity.

Retrieve a fraud report by ARN or transaction ID

Get fraud report details by either:

The ARN (Acquirer Reference Number), or
The original_transaction_unique_id

Request example

<fraud_report_request>
  <arn>74537604221431003881865</arn>
</fraud_report_request>

List all fraud events for a transaction

To retrieve all SAFE/TC40 events related to a single transaction (e.g. multiple fraud entries), include the list element in the request.

Request example

<fraud_report_request>
  <original_transaction_unique_id>53b1f5eacc9e4d3a3afebb4e993fe962</original_transaction_unique_id>
  <mode>list</mode>
</fraud_report_request>

Retrieve fraud reports by date range

You can retrieve all fraud reports for a given merchant by:

post_date (when the transaction was posted)
import_date (when the report was imported into the system)
report_date (the fraud report date)

Each request is paginated and returns a maximum of 100 entries.

Request example

<fraud_report_request>
  <start_date>2025-05-01</start_date>
  <end_date>2025-05-31</end_date>
  <page>1</page>
</fraud_report_request>

Request parameters (date range retrieval)

Parameter	Required	Format	Description
`start_date`	Yes*	yyyy-mm-dd	Start of the requested date range
`end_date`	No	yyyy-mm-dd	End of the requested date range
`import_date`	Yes*	yyyy-mm-dd	Date of import in our system (entire day range)
`report_start_date`	Yes*	yyyy-mm-dd	Start of date range for fraud report date
`report_end_date`	No	yyyy-mm-dd	End of date range for fraud report date
`page`	No	integer	Page number (default: 1)
`per_page`	No	integer	Number of entries per page (default: 100)

Response parameters

Parameter	Format	Description
`arn`	string	ARN of the transaction
`post_date`	yyyy-mm-dd	When the transaction was posted
`reason_code`	string(1)	Fraud report reason code
reason_description	string	Text description of the reason code
`original_transaction_amount`	integer	Original transaction amount in minor units
`original_transaction_currency`	string	Currency of the original transaction
`card_number`	string	Masked card number
`card_brand`	string	Card brand (Visa, Mastercard, etc.)
`customer_email`	string	Email address of the cardholder
`customer_phone`	integer	Phone number of the cardholder
`transaction_type`	string	Type of the original transaction
`original_transaction_unique_id`	string	Unique ID of the original transaction
`chargeback_amount`	integer	Chargeback amount in minor units
`chargeback_currency`	string(3)	Currency of the chargeback transaction
`report_date`	yyyy-mm-dd	Date the fraud report was entered

Fraud report codes

Code	Type	Description
`0`	string(1)	Lost
`1`	string(1)	Stolen
`2`	string(1)	Card not received as issued (NRI)
`3`	string(1)	Fraudulent application
`4`	string(1)	Issuer-reported counterfeit
`5`	string(1)	Miscellaneous / Account takeover
`6`	string(1)	Fraudulent use of account number
`7`	string(1)	(U.S. only) used by ICS
`8`	string(1)	(U.S. only) used by ICS
`9`	string(1)	Acquirer-reported counterfeit

Error response example

If no SAFE/TC40 report is found for the provided identifiers:

<fraud_report_response>
  <status>error</status>
  <code>490</code>
  <message>Mastercard Fraud Report not found!</message>
  <technical_message>Mastercard fraud report by the given criteria cannot be found!</technical_message>
</fraud_report_response>

Was this page helpful?