Skip to main content
Version: 1.0



Endpoint Overview

Our Chargebacks endpoint collects fraud labels. These labels are crucial for the Payment Fraud product as they are used as labels to train 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.

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. 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.
Reason for the chargeback.
Timestamp when a dispute was opened.
External ID of this chargeback, unique for the customer.
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 \
-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"}]}'