1. Integration Guide
Dispute Service API
  • Dispute API
    • Integration Guide
      • Dispute Service Usage Guide
      • Security Requirements and Message Format
      • Special Rules
    • API Reference
      • Dispute
        • Dispute
        • Dispute
      • Notification
        • Dispute Notification
        • Alert Notification
  1. Integration Guide

Dispute Service Usage Guide

This section describes API usage for different business scenarios in the dispute defend flow.

Step1 Chargeback Notification#

After EVO Payment receives dispute information from the Card Scheme, Dispute Service automatically sends a notification for a Chargeback transaction.
The main process is as follows:
When Dispute Service receives a new Chargeback, it will call the Notification API to send a notification to the merchant.
The following is a complete sample of the received Notification.

Step2 Defend#

Dispute APIs are sent by the merchant.

Option1 Accept Dispute#

When the merchant receives a Chargeback notification, the merchant can choose to accept the Chargeback directly without submitting a defend request.
The main process is as follows:
When the merchant receives the notification, the merchant can determine whether to accept the Chargeback based on disputeInfo.result, action.type, and action.suggestion in the notification.
If the merchant accepts it, the merchant needs to call the Dispute API. When calling the API, the request needs to include, but is not limited to, the following parameters. For field details, refer to the API documentation:
disputeMode:Indicates the purpose of this API and is used by the system for identification. In this case, the merchant needs to set it to "ACCEPT_DISPUTE_RESULT".
casoNo:Identifies the case number of this dispute.
In the returned information, disputeInfo.status will become "finished", which indicates that this API request has been processed successfully and the merchant has accepted the Chargeback.
The following is a complete sample of accepting a Chargeback:
Request
Response

Option2 Defend#

When the merchant receives a new Chargeback notification, the merchant can choose to defend it. Related documents are required for defend.
The main process is as follows:
The merchant can determine whether to accept the Chargeback based on disputeInfo.result, action.type, and action.suggestion in the notification. If the merchant does not accept it and needs to defend it, the merchant needs to call the Dispute API. When calling the API, the request needs to include, but is not limited to, the following parameters. For field details, refer to the API documentation:
disputeMode:Indicates the purpose of this API and is used by the system for identification. In this case, it should be set to "DEFENSE_DOCUMENT".
casoNo:Identifies the case number of this dispute.
fileMetaData:Contains the information of uploaded files.
Defend document format: PDF, Word, JPG, and PNG are supported.
The size of a single defend document cannot exceed 5MB. Up to five files can be uploaded at the same time.
Defend documents need to be uploaded in Base64 encoding format.
The returned disputeInfo.status is "inDefense", which indicates that the file upload is successful and EVO Payment starts to process the defend request.
The following is a complete sample of uploading files:
Request
Response

Option2.1 Document Error#

At the start of the defend process, the merchant needs to submit the documents required for defend through API. After the submission is completed, if the document format is incorrect or additional documents are required, Dispute Service will send an API notification to the merchant to supplement documents. After the merchant supplements the latest documents through API, if no further documents are required, the defend process will continue.
The main process is as follows:
a):If the documents are not compliant, Dispute Service will notify the merchant through API that the defend documents are incorrect. The error reason will be specified in the specific field documentErrorRemarks.
b):After receiving the notification, the merchant calls the Dispute API to upload the latest documents. This operation is the same as Step2.Option2 Upload Files. The merchant only needs to set disputeMode to "DEFENSE_DOCUMENT_UPDATE". The returned disputeInfo.status is "continueDefensing", which indicates that the file update is successful and EVO Payment will start to process the defend request after confirming that the documents are correct.
The following are complete API samples of the notification and file upload:
Document Error Notification
Upload Files:
Request
Response

Step3 Defend Result Notification#

After receiving the defend result from the Card Scheme, Dispute Service will send a notification API to notify the user of the result.
The main process is as follows:
After receiving the defend result from the Card Scheme, Dispute Service will send a notification API to notify the merchant of the result. At this time, the merchant can find the corresponding result in the result field and decide whether to continue to defend.
The API structure of the defend result notification is the same as that of the Chargeback notification API. The difference is that the Result field of the Chargeback notification API is fixed as newChargeback, while the defend result notification API uses a combination of result keywords and specific information.

Step4 Result Processing#

Option1 Accept Result#

After receiving the defend result, the merchant can choose to accept the defend result.
The main process is the same as Step2.Option1.

Option2 Continue to Defend#

After receiving the defend result, the merchant can choose to continue to defend.
The main process is the same as Step2.Option2. The subsequent document check/update and result notification are also the same as Option2.1 and Step3.

Query Defend Information#

The merchant can call the query API to query the details of a dispute transaction.
Different query parameters will return different results.
Please note: Currently, Dispute Service only supports querying dispute cases created within one year and with the dispute type of Chargeback. If the creation date of the target case is more than one year ago, it will not be returned.
Query methods:
1.Query by caseNo
Query result: the Chargeback dispute transaction of the specified caseNo.
2.Query by time range
Query result: all Chargeback dispute transactions under the specified store within the specified time range.
When querying, the merchant needs to send the startDate and endDate fields to indicate the query time range. If only startDate or endDate is uploaded, the system will query the Chargeback dispute transactions on the corresponding date of the uploaded field by default.
Example: If the merchant only sends startDate=20250301, all Chargeback dispute transactions under the corresponding store on 20250301 will be queried.
3.Query by merchant transaction ID
Query result: the Chargeback dispute transaction associated with the specified merchant transaction ID.
Please note: If no date is specified, the related Chargeback dispute transactions within the last month will be queried by default.
Before querying, the merchant needs to fill in the corresponding domain name and store ID in the path, and use one of the above methods in the body for the query.
The following is a complete returned sample after querying one piece of dispute information:
Next
Security Requirements and Message Format
Built with