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:

• payment_dispute:read
• payment_dispute:write
• file:upload

To manage disputes for your merchants:

1. Retrieve all disputes for a connected Airwallex account by calling List payment disputesAPI.
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 fileAPI and note the file IDs returned in the response.
4. Call Challenge a payment disputeAPI 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 disputeAPI 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 APIsAPI in the Sandbox environment.