Dispute management

A common use case for payment-related partners is to help merchants manage payment disputes and chargebacks in a timely manner. You can retrieve disputes from connected Airwallex accounts, surface them to merchants for review, and act on them—either by submitting a challenge with evidence or by accepting the dispute—through the Airwallex API.

To build this integration, you need the following OAuth scopes:

• r:awx_action:payment_dispute_view
• w:awx_action:payment_dispute_edit
• w:awx_action:file_upload

To manage disputes for your merchants:

1. Retrieve all disputes for a connected Airwallex account by calling List payment disputes API.
2. Build a dispute management interface that lets merchants review dispute details and decide whether to challenge or accept each one.
3. To challenge a dispute, upload any supporting evidence files using Upload a file API and note the file IDs returned in the response.
4. Call Challenge a payment dispute API with the dispute ID and the evidence file IDs from the previous step.
5. To accept and close a dispute instead, call Accept a payment dispute API with the dispute ID.

As an alternative to periodically polling for new disputes, you can subscribe to dispute-related webhook events to receive notifications when a dispute is created or updated. For more information on setting up webhooks, see Notifications and workflow automation.

To test your integration, use the dispute simulation APIs API in the Sandbox environment.