This endpoint allows you to create a dispute for a chargeback already registered in Asaas by submitting documents and evidence that will be used during the review process.

A dispute is the mechanism used to formally contest a chargeback with the acquirer or institution responsible for the transaction.

When a dispute is created, the submitted documentation becomes part of the case review process and may be used to validate the legitimacy of the disputed charge.

When to use

This endpoint should be used when:

• A chargeback has been opened for a payment.
• There is documentation proving the legitimacy of the transaction.
• The merchant wishes to contest the cardholder's dispute.
• There is evidence demonstrating the delivery of the product or the provision of the service.

Creating a dispute represents the opportunity to submit evidence in an attempt to reverse the chargeback.

Usage dependencies

Before creating a dispute, the following conditions must be met:

1. The chargeback must already exist.
2. The chargeback identifier must be available.
3. The chargeback must allow dispute submission.
4. Supporting documents must be available for upload.

Without these conditions, the dispute cannot be created.

Parameters used

📘

Important

The id parameter corresponds to the chargeback identifier and not to the original payment identifier.

Accepted files

A dispute is created by submitting supporting documentation.

Some examples of commonly used evidence include:

• Proof of delivery.
• Proof of service completion.
• Signed contracts.
• Conversations or communications authorizing the purchase.
• Acceptance confirmations.
• Buyer identification documents.

The endpoint allows up to 11 files per dispute.

🚧

Attention

The more complete the submitted evidence, the greater the chances of an adequate review of the case.

Operation behavior

When creating a dispute:

Chargeback opened
↓
Evidence submission
↓
Dispute created
↓
Documentation review
↓
Dispute outcome

Creating a dispute does not guarantee that the chargeback will be reversed.

The outcome depends on the review performed by the institutions involved in the process.

Request example

POST /v3/chargebacks/{id}/dispute

Example:

POST /v3/chargebacks/cb_123456/dispute

Multipart upload example:

Content-Type: multipart/form-data

files=document1.pdf
files=proof-of-delivery.jpg
files=contract.pdf

Best practices

• Submit clear and legible evidence.
• Prioritize documents directly related to the disputed transaction.
• Gather all required documentation before creating the dispute.
• Avoid submitting duplicate files.
• Keep an internal copy of the submitted documents for future auditing purposes.

📘

Important

After submitting the dispute, it is recommended to monitor the chargeback's progress to track any status updates.

Common errors

Chargeback not found

Occurs when the provided identifier does not exist or does not belong to the authenticated account.

Chargeback not eligible for dispute

Occurs when the chargeback no longer allows dispute submission.

File limit exceeded

Occurs when the maximum allowed number of files is exceeded.

Invalid files

Occurs when one or more submitted documents cannot be processed.

Operational impacts

The dispute is part of the official chargeback contestation process.

If no evidence is submitted within the applicable deadlines, the chances of reversing the chargeback may be reduced.

For this reason, it is recommended to automate evidence submission whenever possible and maintain internal processes for quickly collecting the required documentation.

Recommended flow

A typical integration follows the flow below:

Receive chargeback notification
↓
Retrieve chargeback information
↓
Gather evidence
↓
Create dispute
↓
Monitor review outcome

Next steps

Depending on your integration needs, the following content may complement the implementation:

• Retrieve chargeback.
• List chargebacks.
• Retrieve payments.
• Payment webhooks.