Create disputes
Use this step-by-step guide to create and submit disputes using Airwallex Disputes API.
How it works
The diagram below depicts the information flow in a dispute resolution process via Airwallex Dispute APIs.
Before you begin
- Familiarize yourself with the dispute categories and reasons.
- Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
Step 1: Create a dispute
Use Create a transaction dispute API to create a dispute
object by providing the following fields.
transaction_id
: Retrieve the identifier of the transaction to be disputed.reason
: Provide a dispute reason from the list of available dispute reasons. The dispute reason can be updated later using Update a transaction dispute API before it is submitted to Airwallex.amount
: Optional. Provide the dispute amount. This amount must not be larger than the billing amount of the transaction. If omitted, the billing amount of the transaction will be used.evidence_files
: Optional. Attach files as evidence for the dispute. Obtain thefile_id
by uploading a file using File upload API. One or more files can be attached to a dispute.note
: Optional. Add explanation on why the transaction is disputed. The more information you provide, higher the chances of the dispute being accepted by Airwallex.reference
: Optional. Provide your internal dispute identifier if you have one for ease of reconciliation with internal data.
A successful request returns a dispute object with all the request fields, and the following dispute details:
dispute_id
: A unique identifier of the dispute object. You can use this to:- Update dispute details such as dispute
amount
,reason
,note
,evidence_files
using Update a transaction dispute API. - Retrieve dispute details and status anytime, see Get a dispute.
- Update dispute details such as dispute
status
: The status of the dispute, which remains asDRAFT
until it's submitted via Submit a transaction dispute API. See Dispute statuses.
If a dispute record in DRAFT
status is not submitted to Airwallex within 120 days of the transaction clearing date, the transaction will not have dispute rights and the record will transit to an EXPIRED
status.
Step 2: Submit a dispute
When the dispute
object that you have created has all the information related to the dispute, you can submit it to Airwallex for review using Submit a transaction dispute API. Make sure the dispute is submitted within the applicable time limits for each dispute category, expressed as calendar days from the transaction processing date.
Dispute Category | Time to submit a dispute to Airwallex |
---|---|
Fraud | Within 110 calendar days |
Authorization | Within 65 calendar days |
Processing Error | Within 110 calendar days |
Consumer | Within 110 calendar days |
The time limit set by Airwallex for submitting a dispute includes the time needed by Airwallex Operations to investigate the transaction. Therefore, it is not directly comparable to the time limit set by the card scheme.
A successful submission will return SUBMITTED
status in the response. You can update a submitted dispute using Update a transaction dispute API to provide additional explanation in the note
field or add new evidence_files
to support the dispute.
You can also choose to cancel a submitted dispute using Cancel a transaction dispute API.