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, dispute level, and dispute eligibility for card transaction events.
• Obtain your access tokenAPI 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 disputeAPI to create a dispute object by providing the following fields.

Identify the disputed transaction

Provide exactly one of the following identifiers:

• transaction_id: The identifier of a transaction from the legacy transaction APIs. Retrieve it from Get transactionsAPI. This field is provided for backward compatibility and is unrelated to card_transaction_id in the transaction lifecycle model.
• card_transaction_event_id: The identifier of a specific card transaction event to dispute. Retrieve it from Card transaction eventsAPI. Use this for multi-capture transactions when you need to dispute a single clearing event. The event must meet dispute eligibility requirements.

Provide dispute details

• reason: Provide a dispute reason from the list of available dispute reasons. The dispute reason can be updated later using Update a transaction disputeAPI 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 or event. If omitted, the billing amount is used.
• additional_info: Optional. Provide supporting dates for the dispute reason. See Additional information for the available fields and recommended dispute reasons.
• evidence_files: Optional. Attach files as evidence for the dispute. Obtain the file_id by uploading a file using File uploadAPI. One or more files can be attached to a dispute. Files must be JPEG (max 10 MB) or PDF (max 2 MB). If you attach a file that does not meet those limits, use Update a transaction disputeAPI to replace it with files that do.
• note: Optional. Add an explanation of why the transaction is disputed. The more information you provide, the 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:

• id: A unique identifier of the dispute object. You can use this to:
  • Update dispute details such as dispute amount, reason, note, evidence_files, and additional_info using Update a transaction disputeAPI.
  • Retrieve dispute details and status anytime, see Get a transaction disputeAPI.
• card_transaction_event_id: Present when the dispute was created at the card transaction event level.
• transaction_id: The legacy transaction identifier associated with the dispute, if the dispute was created using transaction_id.
• additional_info: The supporting dates provided in the request, if any.
• status: The status of the dispute, which remains as DRAFT until it's submitted via Submit a transaction disputeAPI. See Dispute statuses.

Example request (legacy transaction)

1{
2  "transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3  "amount": 100.99,
4  "reason": "SUSPECTED_FRAUD",
5  "evidence_files": [
6    "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="
7  ],
8  "note": "The cardholder did not perform the transaction. Refer to the attached evidence.",
9  "reference": "You can insert your internal case identifier here."
10}

Example request (card transaction event)

1{
2  "card_transaction_event_id": "019d90b8-1bfd-7000-8f58-e51c42c718d5",
3  "amount": 0.99,
4  "reason": "GOODS_SERVICE_NOT_RECEIVED",
5  "evidence_files": [
6    "ZjBjMDcyMjEtMGM1ZS00MjM1LWIxYTMtNzBmMzkyNjExNzVjLHwsc2csfCx0b3Atc2VjdGlvbi1iZy5qcGVnXzE3NzU1NDU5MDA1OTQ"
7  ],
8  "note": "The cardholder did not receive the goods.",
9  "reference": "1618",
10  "additional_info": {
11    "expected_delivery_date": "2025-03-01T00:00:00.000+0000"
12  }
13}

Example response

1{
2  "id": "f6a8059e-f085-4ef7-90e8-e32e81425281",
3  "created_at": "2026-04-28T09:24:44.979+0000",
4  "updated_at": "2026-04-28T09:24:44.979+0000",
5  "card_transaction_event_id": "019d90b8-1bfd-7000-8f58-e51c42c718d5",
6  "transaction_id": "d81f210f-38ad-41e4-9c57-1b827b7ce513",
7  "amount": 0.99,
8  "reason": "GOODS_SERVICE_NOT_RECEIVED",
9  "status": "DRAFT",
10  "reference": "1618",
11  "note": "The cardholder did not receive the goods.",
12  "additional_info": {
13    "expected_delivery_date": "2025-03-01T00:00:00.000+0000"
14  },
15  "updated_by": "CUSTOMER"
16}

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 disputeAPI. Make sure the dispute is submitted within the applicable time limits for each dispute category, expressed as calendar days from the transaction processing date.

A successful submission will return SUBMITTED status in the response. You can update a submitted dispute using Update a transaction disputeAPI to provide additional explanation in the note field, add new evidence_files, or update additional_info to support the dispute.

You can also choose to cancel a submitted dispute using Cancel a transaction disputeAPI.

If Airwallex needs more information to review the dispute, it sends the issuing.transaction_dispute.modified webhook. After you receive it, call Get a transaction disputeAPI and check update_history for next steps.

Next steps

• Receive dispute updates
• Dispute statuses
• Dispute error codes