Skip to main content
Version: 1.1

Fraud Notifications Enrichment

Chargebacks

(Please note that the Fraud Notifications Enrichment endpoint was previously named the Chargebacks endpoint)

POST https://api.fraudio.com/v1/transactions/fraud-notifications-enrichment

Endpoint Overview

Our Fraud Notifications Enrichment endpoint collects fraud labels. These labels are considered to be Critical & Required for the Payment Fraud product, as they are used as labels to train our machine learning models. We distinguish between fraud notifications and chargebacks:

  • Fraud notifications are reports from the (cardholder's) bank that flag fraudulent activity.
  • Chargeback events represent the different stages of a chargeback.

The fraud labels can be sent either individually or in batch.

A note on fraud labels

It is sufficient to send only fraud notifications and the first stage of chargebacks (1st chargeback).

Whilst sending other chargeback stages is helpful, doing so is optional, not a requirement. Even if you do have this additional data, we recommend that you send these two labels first.

Request Parameters

Request parameters in JSON format

{
"data": [
{
"transactionid": "00000001",
"timestamp": 1646063615,
"merchant": "346888E3-A907-4D2B-D286-1FBC0BB988D9",
"fraudimportdate": 1602868410.143105,
"chargebackid": "1003125",
"chargebackreason": "10.4",
"fraudreason": "Suspicious account number used",
"reporttype": "1st chargeback"
}
]
}

Request parameters: Field Reference Table

FieldData TypePayment Fraud (Issuer)Payment Fraud (Acquirer / Processor)Merchant Fraud / AMLDescription
transactionidStringCritical & RequiredCritical & RequiredSupplementary
The unique identifier of the transaction event. Every transaction event, so auth, capture, auth_capture, etc., has its own unique ID.
timestampDoubleCritical & RequiredCritical & RequiredSupplementary
The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted.
reporttypeStringCritical & RequiredCritical & RequiredSupplementary
The type of fraud report. Some possible values are fraud notification, 1st chargeback, information supplied, reversed chargeback, pre-arbitration, 2nd chargeback. Please note: 1st chargebacks and fraud notifications are the priority here, especially during integration! Details about each possible value below.
- fraud notification: Fraud activity reported by the (cardholder's) bank. Examples are Visa's TC40 files and MasterCard's SAFE files.
- 1st chargeback: First stage of the chargeback where the disputed amount is withdrawn from the merchant's account.
- information supplied: Defense documents against the 1st chargeback are supplied.
- reversed chargeback: The disputed amount is transferred back to the merchant's account.
- pre-arbitration: Card scheme evaluates the defense.
- 2nd chargeback: 2nd and definite chargeback where the disputed amount is withdrawn from the merchant's account.
merchantStringCritical & RequiredCritical & RequiredSupplementary
The name or identifier of the merchant. This field uniquely identifies the merchant, and should not be confused with the MID. Any name or unique identifier is accepted.
chargebackreasonStringCritical & RequiredCritical & RequiredSupplementary
Reason for the chargeback.
fraudimportdateDoubleImportantImportantSupplementary
Timestamp when a dispute was opened.
chargebackidStringSupplementarySupplementarySupplementary
External ID of this chargeback, unique for the customer.
fraudreasonStringSupplementarySupplementarySupplementary
Reason why the transaction was fraudulent.

Response Parameters

200 OK Response
{
"created": 2,
"deleted": 0,
"errors": 2,
"ignored": 5,
"received": 0,
"updated": 0
}
Status CodeStatus MessageDescriptionSchema
200OKStandard response for successful HTTP requests.200 OK - Post-auth response
4xx, 500, 501, 502, 503, 504errorVarious error messages for unsuccessful HTTP requests.Problem response

Code samples

curl -X POST 'https://api.fraudio.com/v1/transactions/fraud-notifications-enrichment' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data-raw '{"data":[{"chargebackid": "1003125","chargebackreason": "Payment was not authorized","fraudimportdate": 1602868410.143105,"fraudreason": "Suspicious account number used","reporttype": "1st chargeback","merchant": "346888e3-a907-4d2b-d286-1fbc0bb988d9","timestamp": 1646063615,"transactionid": "00000001"}]}'