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:
- API access to dispute endpoints
- Be notified on a dispute event
- Retrieve dispute information
- Understand Airwallex’s auto-response rules
- Upload dispute evidence
- Respond to a dispute event
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 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
| Webhook | Stage | Status | Description |
|---|---|---|---|
| Payment_dispute.requires_response | Pre-chargeback / Chargeback | Requires Response | You have received a pre-chargeback / chargeback request which needs your response. |
| Payment_dispute.pending_closure | Pre-arbitration | Pending Closure | You have received a Pre-arbitration request from the Issuing bank. Airwallex auto-accepts pre-arbitration requests on behalf of you. |
| Payment_dispute.challenged | Chargeback / Pre-arbitration | Challenged | You have further challenged the chargeback or pre-arbitration with your response |
| Payment_dispute.accepted | Pre-chargeback / Chargeback / Pre-arbitration | Accepted | You have accepted the Pre-chargeback / chargeback / Pre-arbitration request |
| Payment_dispute.reversed | Pre-chargeback / Chargeback / Pre-arbitration | Reversed | Issuing bank has reversed the dispute event, you do not have to respond to the dispute event anymore. |
| Payment_dispute.won | Chargeback / Pre-arbitration | Won | You have won the chargeback / Pre-arbitration, no further action needed from your side. |
Less known flow
| Webhook | Stage | Status | Description |
|---|---|---|---|
| Payment_dispute.requires_response | RFI | Requires Response | You have received a request for additional information on the payment transaction. |
| Payment_dispute.challenged | RFI | Challenged | You have challenged RFI request with evidence in response, pending issuer’s review. |
| Payment_dispute.accepted | RFI | Accepted | You have accepted the RFI request, you need to manage the refund by yourself. |
| Payment_dispute.expired | RFI | Expired | Your time to respond for an RFI event has passed, Issuer will most probably escalate this to pre-chargeback / chargeback |
| Payment_dispute.pending_decision | Arbitration | Pending Decision | You have received an Arbitration request. Card schemes will now decide on the outcome of the dispute. |
| Payment_dispute.lost | Pre-arbitration | Lost | Issuing bank didn’t accept the evidence you provided in the chargeback response, no further action possible. |
| Payment_dispute.won | Pre-arbitration | Won | Issuing 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.
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.
- 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.
- Auto-accept pre-chargeback events on your behalf when the transactions is under defined threshold of 60 USD or equivalent.
- 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 brand | File formats supported | Maximum total size | Maximum single file size |
|---|---|---|---|
| MasterCard | tiff, tif, pdf, jpg, jpeg, png | 14.5 MB | N/A |
| VISA | tiff, tif, pdf, jpg, jpeg | 15 MB | pdf : 2 MB, jpeg : 10 MB, tiff : 10 MB |
| AMEX | pdf, tiff, tif, jpg, jpeg, jpg, png, doc, docx | 900 MB | 4 MB |
| UPI | pdf, jpg, jpeg | 15 MB | N/A |
| JCB | pdf, jpg, jpeg | 15 MB | N/A |
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.
| Scenario | Card | Amount |
|---|---|---|
| Chargeback : requires response | 2223000048410010 | 18.01 |
| Chargeback : won | 2223000048410010 | 18.02 |
| Chargeback : reversed | 2223000048410010 | 18.03 |
| Prechargeback : accepted (Auto accepted) | 2223000048410010 | 17.01 |
| Prechargeback : requires response | 2223000048410010 | 70.01 |
| Prechargeback : reversed | 2223000048410010 | 17.03 |
| RFI : requires response | 2222400030000004 | 18.01 |
VISA dispute scenarios
| Scenario | Card | Amount |
|---|---|---|
| Chargeback : requires response | 4012000300001003 | 18.01 |
| Prechargeback : accepted (Auto) | 4012000300001003 | 70.01 |