Skip to main content

​
Overview

Customers can dispute transactions on their card or account for many reasons, ranging from not recognizing the transaction to unauthorized activity. Disputing a transaction involves a series of actions between the parties involved, where supporting documentation is exchanged until a decision is reached on who is financially responsible. To begin the dispute process, open a dispute on a transaction through the Synctera Console or the Disputes API (described below). When the dispute is opened, a Dispute Case is automatically created. The Dispute and Dispute Case track the dispute details, lifecycle, and events during investigation. The Dispute Case and Dispute Lifecycle are described in this article. Through both the Dispute Case in the Synctera Console and the Disputes API, you are guided through the dispute flow. Available actions depend on the payment rail of the original transaction. Once an action is created against a dispute, subsequent actions may become available as the case progresses. Payment-rail–specific behavior differs. For example, card disputes are evaluated and filed with the card network by Synctera on your behalf after evidence is gathered. For card-specific steps, reason codes, and lifecycles, see Card Transaction Disputes. The walkthrough below uses an ACH dispute as the general API example.

​
Webhook Events

To monitor transaction disputes, webhooks are triggered anytime one of the following events occurs: To subscribe to the dispute webhooks refer to the Webhooks Guide.

​
Disputing a Transaction

The following steps walk through disputing a transaction using the Disputes API. Examples use payment_rail = ACH. Refer to the links below for payment-rail–specific details:

Card Transaction Disputes

​
1. Create a Dispute

To create a dispute, use POST /v1/disputes. ACH disputes support incoming ACH credit and debit transactions. The example below uses a personal account, so Regulation E and its applicable deadline fields appear in the response; those fields are omitted for business accounts.
This will return a response with the created dispute.
Note the returned id attribute and the list of available_actions.

​
2. Upload Supporting Documents

Supporting documents can be uploaded to any dispute (ACH or card) with POST /v1/disputes/{dispute_id}/documents. Uploaded files appear on the dispute under dispute_documents and can be referenced from actions via supporting_doc_id when applicable. Optionally set category on upload:
This will return a response with the created document.
Note the returned document id as it can be used in subsequent dispute actions via supporting_doc_id. ACH supporting documents can be up to 14MB. For card disputes, files must be JPEG, PNG, or PDF, max 4.5MB each, and up to 10 documents per dispute. Some card reason codes also require a document with a specific category before the case can be filed — see Card Transaction Disputes.

​
3. Create a Dispute Action

Select the action you wish to create from the list of available_actions on the dispute. To create the action, use POST /v1/disputes/{dispute_id}/actions
This will return a response with the created action.
ACH_RETURN requires a reason_code and corresponding ACH return_code. R10 is valid for UNAUTHORIZED_TRANSACTION. After this action is created, the dispute moves to ACH_AWAITING_APPROVAL while it is reviewed. Uploaded documents remain listed on the dispute under dispute_documents. Although supporting_doc_id is stored from the request, current ACH action responses expose the document through dispute_documents rather than returning supporting_doc_id on the action.

​
4. Monitor for Dispute Updates

When the dispute is updated, a DISPUTE.UPDATED webhook is triggered. The webhook’s event_resource contains the versioned dispute resource; the v1 object has the same shape as a response from GET /v1/disputes/{dispute_id}, including the updated action_history, lifecycle_state, and available_actions. Depending on the update, a final decision may be reached or further actions may be available. If the dispute decision is still ONGOING, review the latest actions and any new supporting documents before continuing. The decoded v1 dispute object after Synctera requests more information is:
In ACH_MORE_INFO_REQUIRED, you can re-submit the same action type (ACH_RETURN with state = CREATE, including reason_code and return_code) after uploading additional documents, or reject the action. Use document IDs from dispute_documents to retrieve contents for review.

​
5. Review Additional Supporting Documents

To retrieve supporting documentation from the dispute, use GET /v1/disputes/documents/{document_id}/contents
The response body contains the document contents and is saved as file.pdf.

​
6. Re-submit the ACH Return

After providing the requested information, re-submit the ACH return using an action listed in available_actions.
This returns the re-submitted action:
The dispute returns to ACH_AWAITING_APPROVAL while Synctera reviews the additional information.

​
7. Review the Final Decision

When the ACH return is accepted, another DISPUTE.UPDATED webhook is sent. You can also retrieve the current state with GET /v1/disputes/{dispute_id}:
An accepted ACH return sets decision to WON and lifecycle_state to ACH_FILED_WITH_NETWORK. A rejected return instead sets decision to LOST and lifecycle_state to ACH_REJECTED.

​
8. Close Dispute

After the dispute reaches a final decision, close it with PATCH /v1/disputes/{dispute_id}:
The response is the updated dispute. Its final decision and lifecycle do not change; status becomes CLOSED, last_updated_time reflects the close, and available_actions remains empty.