Handle transaction disputes

Copy for LLMView as Markdown

A transaction dispute occurs when a cardholder contests the legitimacy of a payment. Customers issued with Airwallex cards can raise a dispute with Airwallex for any of the following reasons:

Fraud: Applicable when the cardholder did not participate in or authorize the transaction.
Authorization: Applicable when the required authorization was not processed for the transaction.
Processing error: Applicable when the transaction was not appropriately processed as per card scheme rules.
Consumer: Applicable when the cardholder has a dispute with a merchant over the goods or services.

Also see dispute reasons applicable to each category.

Raising disputes

Disputes can be raised with Airwallex using the following options:

Contact your Airwallex Account Manager or email [email protected] to initiate the dispute process.
Use Airwallex Dispute APIs API if you want to programmatically manage a high volume of disputes. Dispute APIs allow you to raise disputes and to manage the entire lifecycle of a dispute through to resolution. While it can take up to 100 days for a dispute to resolve, you can receive real-time notifications on the dispute by subscribing to webhook notifications. See Create disputes.

Airwallex will use the information that you provide in the dispute request and initiate a dispute flow with card schemes. The purchase amount is reversed while the dispute process takes place. If the dispute is upheld, this amount is credited back to your account.

Before raising a dispute, ensure the transaction is eligible for a dispute. See Dispute rights and Dispute eligibility.

Dispute level

When you create a dispute via API, provide exactly one of the following identifiers. Providing both in the same request is invalid.

Level	Identifier	When to use
Card transaction event	`card_transaction_event_id`	Dispute a single clearing event. Use this for multi-capture transactions where you need to dispute one clearing amount rather than the entire card transaction.
Transaction (legacy)	`transaction_id`	Dispute a transaction from the legacy transaction APIs. Provided for backward compatibility and is unrelated to `card_transaction_id`.

To retrieve disputes for a card transaction in the transaction lifecycle model, filter by card_transaction_id. This identifier is not accepted when creating a dispute.

Dispute eligibility

A card transaction event is eligible for a dispute only when all of the following conditions are met:

fund_direction is DEBIT.
type is CLEARING.
subtype is CLEARING or PARTIAL_CLEARING.

Each eligible card transaction event can have at most one transaction dispute.

Additional information

When you create or update a dispute, you can provide an additional_info object with dates that support the dispute reason. Supplying this information upfront reduces back-and-forth with Airwallex during review.

Field	Description	Recommended when dispute reason is
`expected_delivery_date`	The date by which the cardholder expected to receive the goods or service.	`GOODS_SERVICE_NOT_RECEIVED`, `GOODS_SERVICE_CANCELED`
`actual_delivery_date`	The date on which the cardholder actually received the goods or service.	`GOODS_SERVICE_NOT_AS_DESCRIBED`, `GOODS_DAMAGED`
`returned_date`	The date on which the cardholder returned the goods or service.	`GOODS_SERVICE_NOT_AS_DESCRIBED`, `GOODS_DAMAGED`
`attempted_return_date`	The date on which the cardholder attempted to return the goods or service.	`GOODS_SERVICE_NOT_AS_DESCRIBED`, `GOODS_DAMAGED`
`card_charge_permission_withdrawn_date`	The date on which the cardholder withdrew permission for the card charge (for example, canceled a subscription or recurring payment).	`RECURRING_CANCELED`
`order_cancellation_date`	The date on which the goods, service, or reservation was canceled.	`GOODS_SERVICE_CANCELED`

All date fields use ISO 8601 format. See Create disputes for request examples.

Dispute reasons

Disputes can be submitted to Airwallex with one of these reasons.

Dispute Reason	Dispute Category	Description
SUSPECTED_FRAUD	Fraud	The cardholder did not participate in or authorize the transaction. There is reason to suspect that the transaction is fraudulent.
UNAUTHORIZED_TRANSACTION	Authorization	The required authorization was not processed for the transaction.
DUPLICATED_TRANSACTION	Processing Error	The transaction was not appropriately processed per the card scheme rules.
PAID_BY_OTHER_MEANS	Consumer	The cardholder has paid the merchant for the goods or service by other means but still got a charge on the card.
GOODS_SERVICE_NOT_AS_DESCRIBED	Consumer	The cardholder has received goods or services that are not as described by the merchant.
GOODS_DAMAGED	Consumer	The cardholder has received damaged goods from the merchant.
GOODS_SERVICE_NOT_RECEIVED	Consumer	The cardholder has not received the goods or services from the merchant.
REFUND_UNPROCESSED	Consumer	The cardholder has requested for a refund but the merchant did not process the refund.
GOODS_SERVICE_CANCELED	Consumer	The cardholder has not canceled the request for the goods or services but still got a charge on the card.
RECURRING_CANCELED	Consumer	The cardholder has canceled a recurring request (e.g Subscription) for the goods or services but still got a charge on the card.
OTHER	-	For any disputes that do not fall into the categories above.

Dispute rights

Airwallex deems the transaction as not eligible for a dispute when the dispute reason is SUSPECTED_FRAUD and the following conditions are met.

The transaction is a successfully authenticated transaction via 3DS.
The POS entry mode of the transaction is either an EMV contact chip transaction or an EMV contactless chip transaction.
The POS entry mode of the transaction is a magstripe transaction and the transaction is a fallback transaction. A fallback transaction occurs when a payment terminal that supports EMV transaction is unable to process the EMV transaction and uses magstripe as a fallback option.

Check the transaction's dispute eligibility before submission as Airwallex will reject the dispute on ineligible transactions.

Was this page helpful?