Fraud Report

The Fraud Alerts API lets you query the fraud alert records that VISA and Mastercard make available to Kushki, without waiting for a file to be delivered manually over SFTP. Use it for automated fraud reporting, reconciliation, and transaction-level lookups. Records come from two card network reports:

TC40 — VISA

SAFE — Mastercard

It covers both card-present and card-not-present transactions, whether they are processed online or offline.

⚠️ Availability: this report is only available for transactions made with VISA and MASTERCARD cards, and only for acquiring merchants.

⛔ Mexico: this report is not available for domestic transactions in Mexico (PROSA). 🇲🇽

⚠️ Customer-level usage: the API is authenticated and consumed at customer level, not at individual merchant or branch level. A single credential gives visibility over all the fraud alerts of the branches associated with that customer. To narrow a query down to one or several specific merchants, use the merchant_id filter (see Filter by merchant (branch) below) — there is no branch-only credential for this endpoint.

The endpoint supports two query modes:

Mode	When to use it
By date range	Retrieves every fraud alert record within a period (`from` / `to`), optionally filtered by `brand`, `country`, `fraud_type` or `merchant_id`
By transaction identifier	Retrieves the record of a specific transaction (`transaction_arn` or `transaction_reference`)

ℹ️ This API replaces the legacy SFTP/CSV fraud report flow. If you are migrating from that flow, contact your Kushki representative to coordinate the transition.

Query by date range

POST /data/v1/fraud
{
  "brand": "VISA",
  "country": "CHL",
  "from": "2026-03-02T15:04:05",
  "to": "2026-05-02T15:04:05",
  "limit": 100,
  "page": 1
}

Returns a paginated list of fraud alert records for the specified period and filters.

⚠️ Age limit: queries are limited to a maximum of 12 months from the current date. A from value older than 12 months returns a validation error.

⚠️ Date format: from and to must use the exact format YYYY-MM-DDThh:mm:ss, with no milliseconds and no time zone. Any other format returns a validation error.

Response:

{
  "data": [
    {
      "source_name": "TC40",
      "transaction_reference": "32160b0d-4591-4691-acc8-44b4c8821627",
      "transaction_arn": "12710244268000000000007",
      "customer_id": "20000000104030134000",
      "merchant_id": "6000000000172710548457113030",
      "merchant_name": "DEMO STORE",
      "acquirer_bin": "021193",
      "masked_pan": "549151XXXXXX7016",
      "reference_number": "426822110550",
      "total_amount": 2900,
      "fraud_type": "00",
      "incoming_date": 1784127600,
      "pos_entry_mode": "81",
      "mcc_code": "5812",
      "purchase_date": "0402"
    },
    {
      "source_name": "SAFE",
      "transaction_reference": "6ef09b5a-6ce6-443e-a7dd-c42024e097b2",
      "transaction_arn": "12231965093000000136802",
      "customer_id": "20000000104030134000",
      "merchant_id": "20000328494375849",
      "merchant_name": "DEMO STORE",
      "acquirer_bin": "026532",
      "masked_pan": "533187XXXXXX2822",
      "reference_number": "509300174610",
      "total_amount": 34761,
      "fraud_type": "06",
      "authorization_code": "556549",
      "card_present_indicator": "0",
      "chargeback_indicator": "3",
      "ecommerce_indicator": "21",
      "reception_date": "20260409",
      "transaction_date": "20260402",
      "transaction_time": "211008"
    }
  ],
  "page": 1,
  "page_size": 100,
  "total": 9,
  "total_pages": 1
}

Query by transaction identifier

POST /data/v1/fraud
{
  "transaction_reference": "32160b0d-4591-4691-acc8-44b4c8821627"
}

Returns a single record in the data array, corresponding to that transaction.

ℹ️ If you send transaction_arn and transaction_reference at the same time, transaction_arn takes precedence and transaction_reference is ignored. In this mode, from and to are not required.

Filter by merchant (branch)

POST /data/v1/fraud
{
  "from": "2026-01-01T00:00:00",
  "to": "2026-06-30T23:59:59",
  "merchant_id": "20000328494375843,20000328494375845,20000328494375849"
}

merchant_id filters the records down to specific branches of the authenticated customer. It does not change the level of the credential; it only narrows the result within what that customer can already see. It does not identify a single transaction, so it must be combined with from and to.

⚠️ Up to 20 comma-separated IDs are supported. Values must not contain spaces, either at the beginning of the value or after a comma — for example, " 20000349344" and "id1, id2" are invalid. Sending merchant_id alone, without from and to, returns a validation error.

Request fields

Field	Required	Description
`from`	Date range mode	Start of the period — `YYYY-MM-DDThh:mm:ss`. Max. 12 months old
`to`	Date range mode	End of the period — `YYYY-MM-DDThh:mm:ss`
`page`	Optional	Page number. Default: `1`
`limit`	Optional	Records per page. Default: `100`. Maximum: `100`
`transaction_arn`	Transaction mode	Acquirer Reference Number of the transaction. Takes precedence over `transaction_reference`
`transaction_reference`	Transaction mode	Kushki transaction reference (UUID). Ignored if `transaction_arn` is also sent
`brand`	Optional	Card brand — `VISA` or `MASTERCARD`
`country`	Optional	Acquiring country — `MEX`, `CHL`, `PER` or `COL`
`fraud_type`	Optional	Fraud type code — see Fraud type values below. The catalog depends on `brand`
`merchant_id`	Optional	One or several branch IDs, comma-separated, with no spaces. Max. 20 values

ℹ️ Sending any field that is not listed above also returns a validation error.

Fraud type values

The fraud_type catalog depends on the card brand (brand). If brand is not specified, values from both catalogs are accepted.

VISA

Value	Definition
`0`	Lost — the cardholder no longer has the card and does not know what happened to it
`1`	Stolen — the cardholder does not have the card and can explain how it was lost
`2`	NRI (Not Received as Issued) — the card was shipped but the cardholder never received it
`3`	Fraud Application — account opened with partially false cardholder information
`4`	Counterfeit — card-present transactions that the cardholder did not authorize
`5`	Miscellaneous — fraud that does not fit any other category
`6`	Fraudulent Use of Account Number — fraudulent use without physical possession of the card
`9`	Counterfeit reported by the acquirer — invalid or unissued BIN
`A`	Incorrect Processing — for example, missing EMV cryptogram or CVV validation
`B`	Account or Credential Takeover
`C`	Merchant Misrepresentation
`D`	Manipulation of Account Holder

Mastercard

Value	Definition
`00`	Lost card fraud
`01`	Stolen card fraud
`02`	Card issued and never received
`03`	Fraudulent application
`04`	Counterfeit card fraud
`05`	Account takeover fraud
`06`	Card-not-present fraud
`51`	Illicit merchant — Mastercard Audit Program
`55`	Payment order modification
`56`	Cardholder manipulation
`57`	Additional fraud type reported by Mastercard through SAFE

Response fields

Records are not normalized between brands — the fields present in each record depend on source_name (TC40 or SAFE).

Field	Present in	Description
`source_name`	TC40, SAFE	Source report and brand of the record
`transaction_reference`	TC40, SAFE	Kushki transaction reference (UUID)
`transaction_arn`	TC40, SAFE	Acquirer Reference Number
`customer_id`	TC40, SAFE	Identifier of the authenticated customer
`merchant_id`	TC40, SAFE	Merchant or branch identifier
`merchant_name`	TC40, SAFE	Merchant or branch name
`acquirer_bin`	TC40, SAFE	Acquirer BIN, six digits
`masked_pan`	TC40, SAFE	Masked PAN — BIN + `XXXXXX` + last four digits
`reference_number`	TC40, SAFE	Reference number of the transaction
`total_amount`	TC40, SAFE	Total amount of the transaction
`fraud_type`	TC40, SAFE	Fraud type code — see Fraud type values above
`incoming_date`	TC40	Unix timestamp of when Kushki received the report
`pos_entry_mode`	TC40	Point of sale entry mode
`fraud_amount`	TC40	Fraud amount reported by the card network
`fraud_currency_code`	TC40	Currency code of the fraud amount — ISO 4217 numeric
`fraud_investigate_status`	TC40	Investigation status of the fraud report, as informed by the card network
`mcc_code`	TC40	Merchant Category Code (MCC)
`purchase_date`	TC40	Purchase date — `MMDD`, for example `0402`
`authorization_code`	SAFE	Bank authorization code
`card_present_indicator`	SAFE	`"0"` or `"1"` — indicates whether the card was present
`chargeback_indicator`	SAFE	Chargeback indicator associated with the record, as reported by Mastercard — for example `"3"`
`ecommerce_indicator`	SAFE	E-commerce indicator of the transaction
`merchant_identifier`	SAFE	Additional merchant identifier assigned by the card network
`reception_date`	SAFE	Date the SAFE report was received — `YYYYMMDD`
`transaction_date`	SAFE	Date the transaction took place — `YYYYMMDD`
`transaction_time`	SAFE	Time the transaction took place — `HHMMSS`
`transaction_amount_usd`	SAFE	Transaction amount converted to USD
`transaction_currency_code`	SAFE	Currency code of the transaction — ISO 4217 numeric
`transaction_currency_exponent`	SAFE	Decimal exponent that applies to the currency

Pagination fields

Field	Description
`page`	Current page returned
`page_size`	Page size applied — equal to `limit`, or `100` by default
`total`	Total number of records that match the filter
`total_pages`	Total number of pages available with the current `page_size`

Errors

Code	Message	Cause
`EDT002`	Invalid request parameters.	`from` and/or `to` are missing in date range mode

These are the conditions that return an error:

Cause	HTTP status
`from` and/or `to` missing in date range mode, or an empty body	400
`from` older than 12 months from the current date	400
`from` or `to` not using the `YYYY-MM-DDThh:mm:ss` format	400
`brand` with a value other than `VISA` or `MASTERCARD`	400
`country` with a value other than `MEX`, `CHL`, `PER` or `COL`	400
`fraud_type` outside the catalog of the specified `brand`	400
`merchant_id` containing spaces, at the beginning of the value or after a comma	400
`merchant_id` with more than 20 comma-separated values	400
`limit` greater than 100	400
Body containing fields that are not part of the request schema	400
`Private-merchant-id` header missing or invalid	401

Authentication

ℹ️ Where to get the credential? You can retrieve it directly from the Kushki Console, under Developers → Credentials. It is not sent to the customer by email and it does not require any request to a Presales Engineer.

⚠️ Despite the name of the header, the credential this endpoint expects is the customer credential, not the credential of an individual branch or merchant. Always authenticate with the customer-level private credential; a branch credential is not valid for this endpoint. To narrow a query down to specific merchants, use the merchant_id field in the body instead of switching credentials.

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available endpoints

Query fraud alerts

Retrieve fraud alert records (TC40/SAFE) by date range or by transaction identifier. Supports pagination.

Got a suggestion on this documentation? Contact us.

Query by date range#

Query by transaction identifier#

Filter by merchant (branch)#

Request fields#

Fraud type values#

VISA#

Mastercard#

Response fields#

Pagination fields#

Errors#

Authentication#

Using the API#

Available endpoints#