Handle disputes using our APIs

To manage your disputes via the Airwallex web app, see Handle disputes on the Airwallex web app.

If you would like to automate the dispute management process, you can use our dispute APIs to manage disputes programmatically from your own systems.

If you have activated AI Dispute Automation on your account, you can also use the AI Dispute Automation Client API to run the same AI-powered dispute flow directly from your own internal tools or case management systems. The Client API lets you:

• Retrieve dispute objects into your internal tools.
• Trigger our AI engine (evidence selection, templating, and narrative/report generation) via API when you challenge a dispute.

This page describes how to:

• Get API access to dispute endpoints
• Receive dispute events via webhooks
• Retrieve dispute information
• Understand Airwallex auto-response rules
• Upload dispute evidence
• Respond to a dispute event (including via the AI Dispute Automation Client API)

1. API access to dispute endpoints
2. Be notified on a dispute event
3. Retrieve dispute information
4. Understand Airwallex’s auto-response rules
5. Upload dispute evidence
6. Respond to a dispute event

Use AI Dispute Automation via Client API

If you are using AI Dispute Automation in the Airwallex Web App, you can extend the same AI-powered dispute experience into your own internal tools by using the AI Dispute Automation Client API.

Instead of manually preparing evidence and drafting dispute reports, your systems can:

• Retrieve disputes programmatically and sync them into your internal case manager or risk tools.
• Trigger our AI engine via API to auto-select and structure evidence, and generate a card-scheme-compliant dispute defense report when you challenge a dispute.

When to use the Client API

Use the Client API if:

• You already manage disputes in your own internal tools or case management systems.
• You want to automate high-volume, low-complexity disputes while still benefiting from Airwallex’s AI dispute engine.
• You prefer not to move operations to the Airwallex Web App but still want AI-optimized dispute packages and reporting.

For customers primarily using the Airwallex Web App, see Automate dispute management with AI for the in-app workflow.

Prerequisites

Before using the AI Dispute Automation Client API:

1. Enable AI Dispute Automation

   • In the Airwallex Web App, activate AI Dispute Automation as described in Automate dispute management with AI.
   • Once enabled, eligible disputes will carry AI metrics (win probability, suggested action, evidence completion) and can be processed via API using the same AI engine.

2. Confirm API access to dispute endpoints

   • Ensure your API key is configured to access the payment dispute endpoints documented on this page.
   • If you have any issues accessing these APIs, contact your Airwallex Account Manager or Customer Support .

3. Enablement and availability

   • The AI Dispute Automation Client API is available for selected merchants and industries.
   • Contact your Airwallex representative if you would like to be onboarded.

High-level integration flow

Once AI Dispute Automation is enabled for your account and you have API access:

1. Receive dispute events via webhooks

   • Subscribe to dispute webhooks and use them as triggers in your internal systems. See dispute notifications for the full list of events.

2. Retrieve disputes into your systems

   • Use the Retrieve Dispute and List Disputes APIs to pull dispute objects into your internal case manager, filtered by stage and status:
     • GET /api/v1/pa/payment_disputes/{dispute_id}
     • GET /api/v1/pa/payment_disputes?stage={stage}&status={status}&reason_code={reason_code}&due_date={due_date}&updated_at={updated_at}
   • See the API reference for request and response details:
     • Retrieve a payment dispute API

3. Upload evidence files

   • Use the File upload API to upload any additional evidence documents not already present in Airwallex, and store the returned file_id values for use in your challenge request.

4. Trigger the AI engine when challenging a dispute

   • When you are ready to challenge a dispute, call the Challenge Dispute API:
     • POST /api/v1/pa/payment_disputes/{dispute_id}/challenge
   • When AI Dispute Automation is enabled on your account, this endpoint will:
     • Leverage the AI dispute engine to select and structure evidence, combining your uploaded documents and Airwallex-held data.
     • Generate the dispute defense report in a card-scheme-compliant format for submission.
   • Refer to the API reference for request/response format and supported fields:
     • Challenge a payment dispute API

5. Monitor outcomes and reporting

   • Continue to use webhooks and the Retrieve Dispute API to monitor dispute status and final outcomes.
   • AI Dispute Automation distinguishes AI-powered challenges from manual ones in the audit history within the Web App; your internal systems can mirror this distinction using your own tagging or metadata scheme.

Step 1 : API access to dispute endpoints

Ensure that your API key is set up to access dispute endpoints API. Please get in touch with your account manager or our support if you are having any problems accessing dispute APIs.

Step 2 : Be notified on a dispute event

Airwallex notifies you of any dispute events via webhooks if you are subscribed. Please refer to Dispute notifications for a complete list of dispute webhooks. Below table depicts events required for you to identify that a dispute event is pending your action.

Standard flow

Less known flow

dispute_id is the key identifier for a dispute event. You can use this identifier to further interact with the dispute APIs in next steps.

Webhook sample

1{
2  "id": "04e0e84622d7b3add4f712dea5abcbeb",
3  "name": "payment_dispute.requires_response",
4  "account_id": "acct_BGEVPKSxP9OjzQGbwxVEKA",
5  "accountId": "acct_BGEVPKSxP9OjzQGbwxVEKA",
6  "data": {
7    "object": {
8      "accept_details": [],
9      "acquirer_reference_number": "24107623281055025187415",
10      "amount": 10,
11      "card_brand": "visa",
12      "challenge_details": [],
13      "created_at": "2023-10-08T06:04:00+0000",
14      "currency": "AUD",
15      "due_at": "2023-10-30T20:00:00+0000",
16      "id": "dst_sgstmr5zzgpg1wsjcwo",
17      "issuer_comment": "",
18      "merchant_order_id": "e837629e-ddc5-462f-aaa1-89536a0abcf9",
19      "mode": "ALLOCATION",
20      "payment_attempt_id": "att_sgstpqlwlgpg1jabmrm_in2ki6",
21      "payment_intent_id": "int_sgstpqlwlgpg1in2ki6",
22      "payment_method_type": "VISA",
23      "reason": {
24        "description": "Other Fraud-Card Absent Environment",
25        "original_code": "10.4",
26        "type": "FRAUDULENT"
27      },
28      "stage": "CHARGEBACK",
29      "status": "REQUIRES_RESPONSE",
30      "updated_at": "2023-10-08T06:04:00+0000"
31    }
32  },
33  "created_at": "2023-05-23T09:50:01+0000",
34  "createdAt": "2023-05-23T09:50:01+0000",
35  "version": "2023-10-01",
36  "sourceId": "int_sgstj9lgrgl82niuabz"
37}
38

Step 3 : Retrieve dispute information

You can either retrieve specific dispute information for further action or directly fetch a list of disputes in particular stage or status pending for your action.

If you have enabled AI Dispute Automation, retrieving disputes via API is typically the first step in syncing cases into your internal tools before triggering the AI engine via the Challenge Dispute API.

Retrieve specific dispute information

Request

GET /api/v1/pa/payment_disputes/{dispute_id}

Sample Response Please see Retrieve a payment dispute API for sample response

Retrieve multiple disputes information

Request

GET /api/v1/pa/payment_disputes?stage={stage}&status={status}&reason_code ={reason_code}&due_date={due_date}&updated_at={updated_at}

You can find the details of stages & status under Dispute flow You can find the reason code details under Dispute response best practices

Sample Response Please see Retrieve a payment dispute API for sample response

Step 4 : Understand Airwallex's auto-response rules

Airwallex has a set of automated rules to manage your disputes effectively by optimizing effort & cost.

1. Auto-defend dispute event on your behalf when there is a full refund posted already. This rule is applicable for all stages except Arbitration. Airwallex will not act automatically when there is no refund or partial refund is in place.
2. Auto-accept pre-chargeback events on your behalf when the transactions is under defined threshold of 60 USD or equivalent.
3. Auto-accept pre-arbitration messages on your behalf. You should reach out to Airwallex support if you would like to further contest a pre-arbitration event.

Given above automation rules, you should not respond to dispute events which satisfy above conditions. You will receive webhook notification of the event moving to subsequent stage / status due to auto action from Airwallex.

Step 5 : Upload dispute evidence

Airwallex offers file service endpoint using which evidence documents can be uploaded, you will receive a File_ID in response which has to be further used in dispute response to refer to evidence documents. You can find more information in the File upload API reference API

Upload file

POST /api/v1/files/upload/{file_path}

Sample response

1{
2  "created": 0,
3  "file_id": "string",
4  "filename": "string",
5  "notes": "string",
6  "object_type": "string",
7  "size": 0
8}

Step 6 : Respond to a dispute event

You can use our dispute API to respond to a dispute event. Generally, the dispute will be in REQUIRES_RESPONSE status (regardless of stage).

• For standard API-only workflows, you provide your own evidence and narrative when calling the Challenge Dispute endpoint.
• For AI Dispute Automation Client API workflows, the same Challenge Dispute endpoint invokes the AI dispute engine (when the feature is enabled on your account) to help select evidence and generate the dispute defense report.

Evidence document restrictions

Request

POST /api/v1/pa/payment_disputes/{dispute_id}/challenge

Sample Response

Please refer to Challenge a payment dispute API for sample response.

Dispute API validation & errors

Invalid parameter

Provided input parameters are not valid, please see below examples

Example#1

1{
2"code": "resource_not_found",
3"source": "dst_unun0vftjgkf8qyhgj4",
4"message": "dispute cannot be found"
5}

Example#2

1{
2"code": "validation_error",
3"message": "document YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ== is too large"
4}

Missing fields

Mandatory input parameters are missing, example:

1{
2"code": "validation_error",
3"message": "accept_reason must be provided"
4}

Invalid operation

Action requested by you is not supported. Ex: Responding to a chargeback which is not in requires_response status:

1{
2"code": "operation_not_supported",
3"message": "operation Submit_evidence is not supported"
4}

Test your Dispute API integration

We understand the need to test your dispute API integration before directly using it in production. You can simulate various dispute scenarios in the sandbox environment using these options:

1. Dispute simulation APIs in the sandbox environment.
2. Dispute simulation by simply creating payments with specific combination of PAN & Amount. Please see below sections for detailed combinations & scenarios.

MasterCard dispute scenarios

Scenario column below depicts the stage & status of the dispute event. Please see Dispute flow for all applicable dispute stage & statuses.

VISA dispute scenarios