Disputes File - Envisso Integration Hub

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.

Column	Type	Required	Description
`environment`	enum	Mandatory	Environment to which the dispute belongs. Allowed: `PRODUCTION`, `TESTING`. Files should only contain records from a single environment.
`dispute_id`	string	Mandatory	Internal 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_id`	string	Mandatory	Legal 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_type`	string	Mandatory	Type of registration ID — see Merchant Registration ID Types. Example: `UEN`.
`merchant_registered_country`	country	Mandatory	Country where the merchant is legally registered — ISO 3166 alpha-2. Example: `SG`.
`transaction_id`	string	Mandatory	ID of the original transaction. IDs longer than 64 characters will be truncated. Example: `6e088a06-3b6f-4b9b-a60a-d2fd985397be`.
`submitted_date_time`	datetime	Mandatory	Time 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_time`	datetime	Optional	Time at which the dispute was resolved — ISO 8601. Unparseable values are nullified. Example: `2024-06-19T09:34:45Z`.
`reason_code`	string	Mandatory	Reason code provided by the payment network. See Dispute Reason Codes. Example: `10.1`.
`resolution_status`	enum	Optional	Final status of the dispute. Allowed: `SETTLED`, `SUCCESSFULLY_DEFENDED`. Invalid values are nullified.
`dispute_currency`	currency	Mandatory	Currency of the dispute — ISO 4217 alpha-3. Example: `USD`.
`dispute_amount`	decimal	Mandatory	Disputed 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.