Skip to main content
Version: 1.1

Dispute Events


Endpoint Overview

Our Dispute Events endpoint collects information related to fraud, such as from the payment dispute process and fraud notifications. Please refer to the list of accepted report types. These are considered to be Critical & Required for the Payment Fraud product:

  • Fraud notifications are alerts issued by card networks, such as Visa's TC40 and Mastercard's SAFE files, indicating potential fraudulent activities identified in card transactions.
  • Chargebacks refer to the sequential stages in a chargeback dispute process, including the 1st chargeback, 2nd chargeback, pre-arbitration, chargeback reversal, and information supplied, each representing different phases of resolution between a cardholder and a merchant.

The dispute event 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",
"statusid": "pending",
"amount": 1.1,
"currency": "978",
"currencyunit": "major"

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. Please note: 1st chargebacks and fraud notifications are the priority here, especially during integration!

Accepted values are:
- 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.
- chargeback reversal: The disputed amount is transferred back to the merchant's account.
- pre-arbitration: A stage in a chargeback dispute where the issuer, unconvinced with the merchant's provided evidence, escalates the case for further review, serving as an intermediate step before potential full arbitration.
- 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.
Timestamp when a dispute was opened.
External ID of this chargeback, unique for the customer.
Reason why the transaction was fraudulent.
The transaction amount in the unit specified by the 'currencyunit' field. Note: The unit used in this field should be explicitly stated in the 'currencyunit' field.
The 3-digit ISO code for the currency used in the transaction.
This field defines the unit of currency used in the 'amount' field. Accepts only major (e.g., 12.30) or minor (e.g., 1230) unit values. This choice should align with the unit used in the 'amount' field.
The Status ID for a dispute or chargeback event is a unique identifier indicating the current status of the process, such as pending, lost, or won. It tracks the event's progression from initiation to resolution.

Response Parameters

Status CodeStatus MessageDescriptionSchema
200OKStandard response for successful HTTP requests.200 OK - Data Collection 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","statusid": "pending","amount": 1.1,"currency": "978","currencyunit": "major"}]}'