Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Back to home
OverviewChoose your payments solutionGet started with payments
Online payments
Invoice integrations
Manage payments
Place a hold on a payment methodCancellationsRefundsDisputes
Dispute flowHandle disputes on the Airwallex web appHandle disputes using our APIs
Dispute response best practicesPre-chargeback programsDispute notificationsAfterpay / Clearpay Disputes
Klarna Disputes
Risk managementReporting
Payment acceptance rate

Handle disputes using our APIs

To manage your disputes via the Airwallex web app, see the detailed steps here .

If you would like to automate the dispute management process you can use our API solution to manage disputes effectively. Below is the summary of steps to be followed to manage disputes using our APIs:

  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

Step 1 : API access to dispute endpoints

Step 2 : Be notified on a dispute event

Airwallex notifies you of any dispute events via webhooks if you are subscribed. Please refer to this page 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

WebhookStageStatusDescription
Payment_dispute.requires_responsePre-chargeback / ChargebackRequires ResponseYou have received a pre-chargeback / chargeback request which needs your response.
Payment_dispute.pending_closurePre-arbitrationPending ClosureYou have received a Pre-arbitration request from the Issuing bank. Airwallex auto-accepts pre-arbitration requests on behalf of you.
Payment_dispute.challengedChargeback / Pre-arbitrationChallengedYou have further challenged the chargeback or pre-arbitration with your response
Payment_dispute.acceptedPre-chargeback / Chargeback / Pre-arbitrationAcceptedYou have accepted the Pre-chargeback / chargeback / Pre-arbitration request
Payment_dispute.reversedPre-chargeback / Chargeback / Pre-arbitrationReversedIssuing bank has reversed the dispute event, you do not have to respond to the dispute event anymore.
Payment_dispute.wonChargeback / Pre-arbitrationWonYou have won the chargeback / Pre-arbitration, no further action needed from your side.

Less known flow

WebhookStageStatusDescription
Payment_dispute.requires_responseRFIRequires ResponseYou have received a request for additional information on the payment transaction.
Payment_dispute.challengedRFIChallengedYou have challenged RFI request with evidence in response, pending issuer’s review.
Payment_dispute.acceptedRFIAcceptedYou have accepted the RFI request, you need to manage the refund by yourself.
Payment_dispute.expiredRFIExpiredYour time to respond for an RFI event has passed, Issuer will most probably escalate this to pre-chargeback / chargeback
Payment_dispute.pending_decisionArbitrationPending DecisionYou have received an Arbitration request. Card schemes will now decide on the outcome of the dispute.
Payment_dispute.lostPre-arbitrationLostIssuing bank didn’t accept the evidence you provided in the chargeback response, no further action possible.
Payment_dispute.wonPre-arbitrationWonIssuing bank has accepted your response, no further action required

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.

JSON
Web-hook sample

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.

Retrieve specific dispute information

Request

Sample Response Please see this page API for sample response

Retrieve multiple disputes information

Request

You can find the details of stages & status under this page You can find the reason code details under this page

Sample Response Please see this page 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 on this topic here API

Upload file

Sample response

Step 6 : Respond to a dispute event

You can use our dispute API to respond to a dispute event, Generally this event will be in Requiresresponse status (irrespective of stage). Please refer to API specification(https://www.airwallex.com/docs/api#/Payment_Acceptance/Payment_Disputes/_api_v1_pa_payment_disputes__id API/get) here for details of the elements.

Evidence document restrictions

Card brandFile formats supportedMaximum total sizeMaximum single file size
MasterCardtiff, tif, pdf, jpg, jpeg, png14.5 MBN/A
VISAtiff, tif, pdf, jpg, jpeg15 MBpdf : 2 MB, jpeg : 10 MB, tiff : 10 MB
AMEXpdf, tiff, tif, jpg, jpeg, jpg, png, doc, docx900 MB4 MB
UPIpdf, jpg, jpeg15 MBN/A
JCBpdf, jpg, jpeg15 MBN/A

Request

Sample Response

Please refer this page API for sample response

Dispute API validation & errors

Invalid parameter

Provided input parameters are not valid, please see below examples

Example#1

Example#2

Missing fields

Mandatory input parameters are missing, example:

Invalid operation

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

Test your Dispute API integration on demo

It is not easy for you to simulate dispute scenarios to test your API integration, we understand the need to test your dispute API integration before directly using it in production. Hence, we have enhanced our demo systems to enable you to simulate various dispute scenarios by simply creating payments with specific combination of PAN & Amount.

MasterCard dispute scenarios

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

ScenarioCardAmount
Chargeback : requires response222300004841001018.01
Chargeback : won222300004841001018.02
Chargeback : reversed222300004841001018.03
Prechargeback : accepted (Auto accepted)222300004841001017.01
Prechargeback : requires response222300004841001070.01
Prechargeback : reversed222300004841001017.03
RFI : requires response222240003000000418.01

VISA dispute scenarios

ScenarioCardAmount
Chargeback : requires response401200030000100318.01
Prechargeback : accepted (Auto)401200030000100370.01
On this page