Skip to main content

Download CSV template

Disputes file template with column headers and descriptions.

​
Overview

Context — All disputes (previously known as chargebacks) that have been newly submitted or had a change in status. File Type — CSV File Name — <company_name>_disputes_YYYYMMDDHHmmSS
  • Example: <company_name>_disputes_20221110233030
  • company_name = your company’s name
Frequency — Daily

​
Data Columns

The following table outlines the column definitions for the dispute data, which was previously referred to as chargebacks in earlier versions of this specification. Each row represents a dispute case received by Payment Service Providers (PSPs) from payment networks like Visa and Mastercard.
ColumnTypeRequiredDescription
environmentenumMandatoryEnvironment to which the dispute belongs. Allowed: PRODUCTION, TESTING. Files should only contain records from a single environment.
dispute_idstringMandatoryInternal dispute ID in the PSP system. Must be unique; duplicates will be merged using the latest version by ingestion time. If the PSP system uses the transaction ID as the dispute ID and multiple disputes exist for a single transaction, disambiguate by appending a serial number (e.g. 54b99bae60ec4480-1). IDs longer than 64 characters will be truncated.
merchant_registration_idstringMandatoryLegal registration ID of the merchant. If no matching merchant exists at processing time, a new merchant is created in an INACTIVE state until a matching record arrives via the merchants file. See Merchant Registration ID Types.
merchant_registration_id_typestringMandatoryType of registration ID — see Merchant Registration ID Types. Example: UEN.
merchant_registered_countrycountryMandatoryCountry where the merchant is legally registered — ISO 3166 alpha-2. Example: SG.
transaction_idstringMandatoryID of the original transaction. IDs longer than 64 characters will be truncated. Example: 6e088a06-3b6f-4b9b-a60a-d2fd985397be.
submitted_date_timedatetimeMandatoryTime at which the dispute was received from the payment network — ISO 8601. Ideally UTC with a Z designator or UTC offset. Example: 2024-06-19T09:34:45Z.
resolution_date_timedatetimeOptionalTime at which the dispute was resolved — ISO 8601. Unparseable values are nullified. Example: 2024-06-19T09:34:45Z.
reason_codestringMandatoryReason code provided by the payment network. See Dispute Reason Codes. Example: 10.1.
resolution_statusenumOptionalFinal status of the dispute. Allowed: SETTLED, SUCCESSFULLY_DEFENDED. Invalid values are nullified.
dispute_currencycurrencyMandatoryCurrency of the dispute — ISO 4217 alpha-3. Example: USD.
dispute_amountdecimalMandatoryDisputed amount in the main unit of the currency, no thousand delimiters, dot as decimal separator. Amounts are rounded per Unicode CLDR. Negative values are converted via absolute value. Zero-amount records are rejected. Example: 20.00.
Invalid values for any mandatory column will cause the record to be rejected and it must be re-sent in a subsequent file.