Simulate payment disputes

You can conduct unit and end-to-end testing of your payments disputes integration by simulating dispute creation, resolution and escalation in the sandbox environment. Airwallex acts as the dispute management entity of the payment processor in these scenarios to produce the simulated result.

Key simulation scenarios include:

• Create, resolve, and escalate payment disputes

Create a payment dispute

Call Create a PaymentDispute API to simulate a payment dispute that requires a response from the merchant.

Provide the following fields in the request body:

• payment_intent_id: Get a PaymentIntent ID from Get list of PaymentIntents API.
• stage: The dispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, or PRE_ARBITRATION.
• reason_code: A valid reason code for the given processor. See test reason codes.
• due_at: Provide a due date for the dispute.
• amount: The dispute amount in the original currency.
• comment: Description of why the dispute has been raised.
• documents: A list of file IDs providing the supporting evidence for the dispute.

Shell
1curl --request POST
2--url 'https://api-demo.airwallex.com/api/v1/simulation/pa/payment_disputes/create'
3--header 'Content-Type: application/json'
4--header 'Authorization: Bearer <your_bearer_token>'
5--data '{
6  "amount": 100,
7  "comment": "The payment is fraudulent",
8  "documents": [
9    "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ"
10  ],
11  "due_at": "2025-05-20T13:14:00+0000",
12  "payment_intent_id": "int_sgstrq84lh7l055b6or",
13  "reason_code": "4837",
14  "stage": "CHARGEBACK"
15}'

The response object will be the same as Retrieve a PaymentDispute API.

Resolve a payment dispute

Resolving the dispute transitions the dispute to the final status. Call Resolve a PaymentDispute API with the following fields:

• in_favor_of: If specified as MERCHANT, the dispute status transitions to WON or REVERSED. If specified as CUSTOMER, the dispute status transitions to LOST.
• amount: The resolved amount. Defaults to the full disputed amount.
• comment: Description of why the dispute was resolved.

Shell
1curl --request POST
2--url 'https://api-demo.airwallex.com/api/v1/simulation/pa/payment_disputes/dst_hkpdw2eqp9oie/resolve'
3--header 'Content-Type: application/json'
4--header 'Authorization: Bearer <your_bearer_token>'
5--data '{
6  "amount": 100,
7  "comment": "The evidence is compelling.",
8  "in_favor_of": "MERCHANT"
9}'

The response object will be the same as Retrieve a PaymentDispute API.

Escalate a payment dispute

Call Escalate a PaymentDispute API with the Payment Dispute ID to decline the evidence provided by the merchant and escalate the dispute to the next stage if needed.

Specify the new due date of the dispute in the due_date field.

Shell
1curl --request POST
2--url 'https://api-demo.airwallex.com/api/v1/simulation/pa/payment_disputes/string/escalate'
3--header 'Content-Type: application/json'
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{
6  "amount": 100,
7  "comment": "The evidence does not prove the payment is valid. Please submit delivery document.",
8  "documents": [
9    "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ"
10  ],
11  "due_at": "2025-08-14T09:14:00+0000"
12}'

Troubleshooting

You might encounter the following errors when simulating payment APIs.