API - Disputes API 2.9.0

Version 2.9.0 (Changes compared to version 2.8.0)

Effective 20th January 2026, 9th September 2025.

Summary

New optional fields added.

Features

Below changes effective from 20th January 2026.

1. GET 'Retrieve a Single Dispute by ID' endpoint: If the Acquirer submits any evidence as an attachment while taking action on the chargeback, certain attachment formats will be converted to a different format based on the institution-level configuration. For instance, '.docx' files will be converted to '.tiff'. Currently, the 'Retrieve a Single Dispute by Id' endpoint displays both the original and converted documents under the 'documents' object. With this change, the original documents will be omitted from the API response under the 'documents' object for this scenario, and only the converted document will be displayed. The converted document is the only document sent to the scheme, which the Acquirer requires for future reference.
2. GET 'Retrieve a Single Dispute by ID' endpoint: A new field, 'errorMessage,' has been added under both the 'previousActions' object and the 'documents' object in the API response body. Currently, when the Acquirer takes action on an incoming chargeback, the action is staged in the database through the API. During the end-of-cycle process, these actions are sent to the scheme, and if any errors occur, the error messages are stored in the database against the case. However, these error messages are not displayed when the Acquirer views the detailed data for the chargeback using this endpoint; only the status of the action and the status of the document are shown. With this change, the Acquirer will now be able to view the detailed error messages explaining why the action was not successfully processed by the scheme.
3. GET 'Retrieve a Single Dispute by ID' endpoint: A new field, 'workByDate' has been introduced in the API response body. This field specifies the last date when the merchant can take action on the chargeback, formatted as YYYY-MM-DD. The 'workByDate' is calculated for the merchant's reference based on the acquirer's configuration. Generally, the acquirer reserves a few days from the overall due date and provides the remaining days for merchants to review and act, allowing the acquirer to assess the merchant's actions and make a final decision accordingly.
4. New field 'closedDate' has been added in GET Disputes and GET Disputes by ID endpoint's API response body.

Below changes effective from 9th September 2025.

1. POST 'Execute an Action' endpoint: The 'evidence' field, currently mandatory for action code '115' (i.e. Rejecting the incoming MasterCard Pre-Arbitration), has been changed to optional.
2. GET 'Retrieve a Single Dispute by ID' and 'List Disputes' endpoint: Currently, the 'result' field in the API response indicates whether the Visa chargeback case has been WON, LOST, or LETTER by the merchant upon closure. A new ENUM value, 'SPLIT,' has been added to this field to account for cases where a partial amount is accepted by either party or Visa's final ruling process.
3. GET 'Retrieve a Single Dispute by ID' endpoint: Six new ENUM values have been added to the 'description' field under the 'documents' object as follows. Currently, for Visa chargeback cases, after the ARBITRATION or COMPLIANCE stage, OmniPay updates the chargeback case document status to 'FINAL_DECISION' based on the Visa Final ruling process. With this change, the description will provide more granular detail with the following ENUM values:
   VCR_ARBITRATION_SPLIT
   VCR_ARBITRATION_WON
   VCR_ARBITRATION_LOST
   VCR_COMPLIANCE_SPLIT
   VCR_COMPLIANCE_WON
   VCR_COMPLIANCE_LOST

Below changes effective from 20th May 2025.

1. 'Retrieve a Single Dispute by Id' endpoint - A new field, 'merchantName,' has been added. Additionally, new fields 'userName,' 'updatedBy,' and 'updatedAt' have been introduced under the 'notes' object. The length of the existing field 'createdBy' in this object has been increased from 50 to 100.
2. 'Add a Note' endpoint - A new optional field, 'userName,' has been included in both the API request body and the API response body. This allows the user to provide the individual username of the person who added the notes for reference or reporting purposes. Additionally, the length of the existing field 'createdBy' in the API response body has been increased from 50 to 100.

Improvements

N/A

Misc Notes

N/A