Payment Disputes
A dispute occurs when a shopper contests legitimacy of a payment. PaymentDispute APIs will enable you to manage your dispute events removing the need to managing dispute events manually via web-app, there by reducing your manual efforts.
Combination of a stage & status of a PaymentDispute will indicate the current situation of dispute. You can use our product documentation to understand the possible next actions based on stage & status combination.
Data Retention Policy: You can query and operate PaymentDispute resources for a maximum of 2 years since creation.
GET /api/v1/pa/payment_disputes/{id}GET /api/v1/pa/payment_disputesPOST /api/v1/pa/payment_disputes/{id}/acceptPOST /api/v1/pa/payment_disputes/{id}/challengeGET /api/v1/pa/payment_disputes/{id}/related_payment_intentsPOST /api/v1/pa/payment_disputes/{id}/update
Retrieve a PaymentDispute
GET /api/v1/pa/payment_disputes/{id}
Retrieve PaymentDispute information using PaymentDispute unique identifier.
PaymentDispute unique identifier.
Further details on why the client is accepting the PaymentDispute event.
The time when the user accepted the PaymentDispute.
User unique identifier of person/system actioned on case.
The accept description.
The accept reason. One of
AGREEMENT_REACHED_WITH_CUSTOMERCUSTOMER_RELATIONSHIP_MAINTENANCELOW_VALUE_TRANSACTIONVALID_CUSTOMER_DISPUTENO_ACTION_TAKEN_BY_MERCHANTRDR_AUTO_ACCEPTEDCOLLABORATION_ACCEPTED_MANUALCOLLABORATION_AUTO_ACCEPTEDCOLLABORATION_AUTO_ACCEPTED_BY_EXPIRYOTHERS
The Refund requested to be created.
The refund amount when accepting RFI. If not specified, it will be same as the remaining amount that has been captured but not yet refunded. Please refer to supported currencies for supported minor units.
The refund reason when accepting RFI. OTHERS is used by default. One of REQUESTED_BY_CUSTOMER, DUPLICATE, FRAUDULENT, ABANDONED, and OTHERS
The stage when dispute is accepted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION.
The acquirer reference number of original payment.
Information about AI dispute automation, including recommendation and current status. Applicable only when the stage is CHARGEBACK.
The AI recommendation for the dispute, present when status is AVAILABLE.
The recommended action. Possible values: Challenge, Accept.
The evidence fields listed below are recommended for challenging this dispute.
For field definitions and accepted values,
refer to the evidence object in Challenge a PaymentDispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
PaymentDispute amount.
The card brand of original payment, applicable when payment_method_type is CARD. Possible values: visa, mastercard, maestro, union pay, american express, jcb, diners club international and discover.
The challenge data submitted at each stage.
The method used to challenge the dispute. Possible values:
- AI_DISPUTE_AUTOMATION: Challenge via AI Dispute Automation
- Applicable when PaymentDispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when PaymentDispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges PaymentDispute.
User unique identifier of person/system challenges PaymentDispute.
Customer information.
Customer billing address.
Customer device unique identifier.
Customer email.
Customer ip.
Customer name.
Customer phone number.
The delivery information.
The shipping address. Applicable at stage RFI.
The date when services or goods are delivered.
The amount of shipping fee. Applicable at stage RFI.
The currency of shipping fee. Applicable at stage RFI.
The recipient's name. Applicable at stage RFI.
The recipient's phone number. Applicable at stage RFI.
The shipping date (the expected delivery date for RFI).
The company name managing this delivery, such as asendia-usa, 4px, and so on.
The shipping method, such as Priority Mail, Flat rate, and so on. Applicable at stage RFI.
The shipping status, such as SHIPPED, DELIVERED, and so on. Applicable at stage RFI.
The shipping tracking number.
The evidence submitted when challenge_method is AI_DISPUTE_AUTOMATION.
File unique identifiers of access activity files. Provide screenshots from your activity log that show the customer's on-site behaviour, such as login times or download timestamps. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of authenticity proof files. Provide documentation that confirms your products are genuine and not counterfeit. This can include certificates, supplier invoices, or brand authorization letters. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of customer communication files. Provide copies of any emails, chat logs, or messages with the customer that show communication before or after the purchase. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Acquirer reference number of the duplicate transaction.
Explanation of the duplicate transaction.
File unique identifiers of duplicate payment files. Provide documents that show how this transaction differs from any potential duplicates. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Amount and currency of the duplicate transaction.
Creation date of the duplicate transaction.
Description of the merchant's business model.
Date and time when the order was fulfilled.
File unique identifiers of order fulfillment files. Provide screenshots of delivery confirmation or shipment tracking information that clearly show the order was successfully delivered. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of order snapshot files. Provide screenshots of the customer's receipt or order confirmation page as evidence that the customer placed the order. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous won disputes on same card. Provide evidence of any previous disputes that you won for transactions using the same card. This helps establish a history of legitimate transactions. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous purchases of similar products. Provide proof of the customer's past purchases of similar items to show their history and relationship with your business. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of product usage files. Provide evidence that the customer has used the product or service, such as a login record or usage timestamp. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Description of the product.
File unique identifiers of product snapshot files. Provide a screenshot of the product page or a photo of the item to show that the product matches its description. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers for your refund policy documents. Upload all documents that describe your refund policy. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
URL of the refund policy page.
File unique identifiers of user agreement files. Upload your user agreement forms that outline the terms and conditions for your customers. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
The order information. Applicable when the stage is RFI.
Time at which this order was created.
The order unique identifier.
The invoice number of order.
The products of order.
Product category at the merchant store, such as home furnishings, pet supplies, apparel and accessories
Merchant’s product identifier code. Maximum of 128 characters.
Product description. Maximum of 500 characters.
The effective end time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The effective start time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The preview image url for this product, which is usually displayed as thumbnail in the order details.
Name of the product. Maximum of 255 characters.
Product quantity
Seller info of the purchase order
The identifier of the seller in the merchant's system
The name of the seller in the merchant's system
Stock keeping unit. A unique identifier assigned by the merchant to identify and track this specific product. Maximum of 128 characters.
Type of product, such as physical_good, intangible_good, or service. Maximum of 128 characters.
Product unit price
The url that links to the product page at merchant site.
The total amount of order.
The currency of total amount.
The description of product.
The type of Product.
The reason why the merchant challenges the dispute. Possible values:
- CUSTOMER_WITHDRAWN: The customer withdrew the dispute
- CUSTOMER_REFUNDED: The customer has already been refunded
- PRODUCT_RECEIVED: The customer has already received / will receive the product or service
- PURCHASE_HISTORY: The customer has a purchasing history with me
- NOT_ENTITLED: The customer is not entitled to refund
- SEPARATE_PRODUCT: The customer purchased separate products or services
- AUTHENTIC_PRODUCT: The product is not damaged, defective or counterfeit
- OTHER_REASONS: Other reasons for challenging
Explanation of why refund is refused.
Merchant information.
Seller name.
Store name.
Store physical address.
Store URL.
The stage when evidence is submitted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK.
The file unique identifiers of support documents.
The file IDs of customer communication. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of customer signature. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
List of documents.
Additional file descriptions or explanations.
File unique identifiers of the documents.
Type of the documents. Possible values: PRIMARY, ORDER, CUSTOMER, OTHER.
- PRIMARY: The primary evidence depends on the challenge reason.
- ORDER: Order related evidence.
- CUSTOMER: Customer related evidence.
- OTHER: Other supporting evidence.
The file IDs of duplicate payment evidence. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file unique identifiers of the files generated by Airwallex automatically based on text evidence or refund information.
The list of file IDs of other documents.
Deprecated. Use documents instead.
The file IDs of proof of delivery. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the receipt. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the refund policy. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
Time at which this PaymentDispute was created.
PaymentDispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
PaymentDispute due date.
PaymentDispute unique identifier.
The issuer’s comment on PaymentDispute.
The issuer’s documents on PaymentDispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
PaymentDispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
PaymentAttempt unique identifier.
PaymentIntent unique identifier.
The payment method type of original payment.
PaymentDispute reason.
PaymentDispute reason description.
PaymentDispute reason code.
PaymentDispute reason type. Possible values: CREDIT_NOT_PROCESSED, FRAUDULENT, DUPLICATE_CHARGE, PRODUCT_NOT_RECEIVED, PRODUCT_UNACCEPTABLE, UNRECOGNIZED_CHARGE, CANCELLED_PRODUCT, MISREPRESENTATION, COUNTERFEIT_PRODUCT, PROCESSING_ERRORS, AUTHORIZATION, NOT_RECOGNIZED, BANK_REJECTION, FUND_REVERSAL, CONSUMER_DISPUTE, POINT_OF_INTERACTION_ERROR and UNKNOWN.
The Refunds of original payment.
The acquirer reference number of Refund.
Refund unique identifier.
PaymentDispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
PaymentDispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the PaymentDispute.
- Applicable when receive notification from card schemes that PaymentDispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the PaymentDispute.
- Applicable when you challenge the PaymentDispute. At
PRE_CHARGEBACKstage, the issuing bank will escalate to the chargeback stage in the following days. AtRFI,CHARGEBACK, andPRE_ARBITRATIONstage, the issuing bank will review your submitted evidence and decide whether to escalate the PaymentDispute or not.
- Applicable when you challenge the PaymentDispute. At
- ACCEPTED: In this status the PaymentDispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the PaymentDispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the PaymentDispute at
- REVERSED: In this status, the PaymentDispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the PaymentDispute decision in your favor. No further action is required.
- Applicable at
CHARGEBACK,PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- LOST: In this status, the issuing bank has not accepted the evidence provided by you, or card schemes have ruled the PaymentDispute decision in Issuer’s favor. No further action is required.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- PENDING_CLOSURE: In this status, the issuing bank has escalated the PaymentDispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the PaymentDispute. Airwallex will decide whether to accept the PaymentDispute or respond to it on your behalf and may reach out to you for more information.- Applicable at
PRE_ARBITRATIONstage.
- Applicable at
- EXPIRED: In this status, the
RFIevent has expired as you have not responded to the request within 15 days.- Applicable at
RFIstage.
- Applicable at
- PENDING_DECISION: In this status, we have responded to the issuing bank with evidence provided by you. The issuing bank will review your submitted evidence and decide whether to accept the PaymentDispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this PaymentDispute was updated or operated on.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 403 | Forbidden |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api-demo.airwallex.com/api/v1/pa/payment_disputes/dst_hkpdw2eqp9oie' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "id": "dst_hkpdw2eqp9oie",3 "stage": "CHARGEBACK",4 "status": "ACCEPTED",5 "amount": 100,6 "currency": "USD",7 "mode": "COLLABORATION",8 "merchant_order_id": "D202503210001",9 "payment_intent_id": "int_hkpdskz7vg1xc7uscdj",10 "payment_attempt_id": "att_hkpdw2eqp9oie",11 "acquirer_reference_number": "T1234567890",12 "payment_method_type": "VISA",13 "issuer_comment": "",14 "issuer_documents": [],15 "card_brand": "visa",16 "reason": {17 "original_code": "4837",18 "description": "Fraudulent transaction",19 "type": "FRAUDULENT"20 },21 "accept_details": [22 {23 "stage": "CHARGEBACK",24 "reason": "AGREEMENT_REACHED_WITH_CUSTOMER",25 "description": "Accepted",26 "refund": {27 "amount": 100,28 "reason": "REQUESTED_BY_CUSTOMER"29 },30 "accepted_by": "airwallex",31 "accepted_at": "2023-10-01T10:00:00+0000"32 }33 ],34 "challenge_details": [],35 "due_at": "2023-11-01T10:00:00+0000",36 "transaction_type": "PAYMENT",37 "customer_name": "John Doe",38 "created_at": "2023-10-01T10:00:00+0000",39 "updated_at": "2023-10-01T10:00:00+0000"40}
Get list of PaymentDisputes
GET /api/v1/pa/payment_disputes
Retrieve list of PaymentDisputes using stage, status, reason code, due date, created time or updated time.
The customer unique identifier of original payment.
The customer name of original payment.
The start time of created_at in ISO8601 format.
The start time of due_at in ISO8601 format.
The start time of updated_at in ISO8601 format.
The order unique identifier of original payment.
0 or the BASE 64 encoded resource unique identifier of PaymentDispute and navigation direction to indicate the page should be returned. 0 is used by default for initial page
PaymentDispute status.
The payment method type of original payment.
PaymentDispute reason code.
Number of PaymentDisputes to be listed per page. Default value is 10. Maximum is 1000. The value greater than the maximum will be capped to the maximum.
PaymentDispute stage.
PaymentDispute status.
The end time of created_at in ISO8601 format.
The end time of due_at in ISO8601 format.
The end time of due_at in ISO8601 format.
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
The list of PaymentDisputes
Further details on why the client is accepting the PaymentDispute event.
The time when the user accepted the PaymentDispute.
User unique identifier of person/system actioned on case.
The accept description.
The accept reason. One of
AGREEMENT_REACHED_WITH_CUSTOMERCUSTOMER_RELATIONSHIP_MAINTENANCELOW_VALUE_TRANSACTIONVALID_CUSTOMER_DISPUTENO_ACTION_TAKEN_BY_MERCHANTRDR_AUTO_ACCEPTEDCOLLABORATION_ACCEPTED_MANUALCOLLABORATION_AUTO_ACCEPTEDCOLLABORATION_AUTO_ACCEPTED_BY_EXPIRYOTHERS
The Refund requested to be created.
The refund amount when accepting RFI. If not specified, it will be same as the remaining amount that has been captured but not yet refunded. Please refer to supported currencies for supported minor units.
The refund reason when accepting RFI. OTHERS is used by default. One of REQUESTED_BY_CUSTOMER, DUPLICATE, FRAUDULENT, ABANDONED, and OTHERS
The stage when dispute is accepted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION.
The acquirer reference number of original payment.
Information about AI dispute automation, including recommendation and current status. Applicable only when the stage is CHARGEBACK.
The AI recommendation for the dispute, present when status is AVAILABLE.
The recommended action. Possible values: Challenge, Accept.
The evidence fields listed below are recommended for challenging this dispute.
For field definitions and accepted values,
refer to the evidence object in Challenge a PaymentDispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
PaymentDispute amount.
The card brand of original payment, applicable when payment_method_type is CARD. Possible values: visa, mastercard, maestro, union pay, american express, jcb, diners club international and discover.
The challenge data submitted at each stage.
The method used to challenge the dispute. Possible values:
- AI_DISPUTE_AUTOMATION: Challenge via AI Dispute Automation
- Applicable when PaymentDispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when PaymentDispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges PaymentDispute.
User unique identifier of person/system challenges PaymentDispute.
Customer information.
Customer billing address.
Customer device unique identifier.
Customer email.
Customer ip.
Customer name.
Customer phone number.
The delivery information.
The shipping address. Applicable at stage RFI.
The date when services or goods are delivered.
The amount of shipping fee. Applicable at stage RFI.
The currency of shipping fee. Applicable at stage RFI.
The recipient's name. Applicable at stage RFI.
The recipient's phone number. Applicable at stage RFI.
The shipping date (the expected delivery date for RFI).
The company name managing this delivery, such as asendia-usa, 4px, and so on.
The shipping method, such as Priority Mail, Flat rate, and so on. Applicable at stage RFI.
The shipping status, such as SHIPPED, DELIVERED, and so on. Applicable at stage RFI.
The shipping tracking number.
The evidence submitted when challenge_method is AI_DISPUTE_AUTOMATION.
File unique identifiers of access activity files. Provide screenshots from your activity log that show the customer's on-site behaviour, such as login times or download timestamps. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of authenticity proof files. Provide documentation that confirms your products are genuine and not counterfeit. This can include certificates, supplier invoices, or brand authorization letters. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of customer communication files. Provide copies of any emails, chat logs, or messages with the customer that show communication before or after the purchase. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Acquirer reference number of the duplicate transaction.
Explanation of the duplicate transaction.
File unique identifiers of duplicate payment files. Provide documents that show how this transaction differs from any potential duplicates. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Amount and currency of the duplicate transaction.
Creation date of the duplicate transaction.
Description of the merchant's business model.
Date and time when the order was fulfilled.
File unique identifiers of order fulfillment files. Provide screenshots of delivery confirmation or shipment tracking information that clearly show the order was successfully delivered. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of order snapshot files. Provide screenshots of the customer's receipt or order confirmation page as evidence that the customer placed the order. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous won disputes on same card. Provide evidence of any previous disputes that you won for transactions using the same card. This helps establish a history of legitimate transactions. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous purchases of similar products. Provide proof of the customer's past purchases of similar items to show their history and relationship with your business. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of product usage files. Provide evidence that the customer has used the product or service, such as a login record or usage timestamp. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Description of the product.
File unique identifiers of product snapshot files. Provide a screenshot of the product page or a photo of the item to show that the product matches its description. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers for your refund policy documents. Upload all documents that describe your refund policy. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
URL of the refund policy page.
File unique identifiers of user agreement files. Upload your user agreement forms that outline the terms and conditions for your customers. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
The order information. Applicable when the stage is RFI.
Time at which this order was created.
The order unique identifier.
The invoice number of order.
The products of order.
Product category at the merchant store, such as home furnishings, pet supplies, apparel and accessories
Merchant’s product identifier code. Maximum of 128 characters.
Product description. Maximum of 500 characters.
The effective end time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The effective start time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The preview image url for this product, which is usually displayed as thumbnail in the order details.
Name of the product. Maximum of 255 characters.
Product quantity
Seller info of the purchase order
The identifier of the seller in the merchant's system
The name of the seller in the merchant's system
Stock keeping unit. A unique identifier assigned by the merchant to identify and track this specific product. Maximum of 128 characters.
Type of product, such as physical_good, intangible_good, or service. Maximum of 128 characters.
Product unit price
The url that links to the product page at merchant site.
The total amount of order.
The currency of total amount.
The description of product.
The type of Product.
The reason why the merchant challenges the dispute. Possible values:
- CUSTOMER_WITHDRAWN: The customer withdrew the dispute
- CUSTOMER_REFUNDED: The customer has already been refunded
- PRODUCT_RECEIVED: The customer has already received / will receive the product or service
- PURCHASE_HISTORY: The customer has a purchasing history with me
- NOT_ENTITLED: The customer is not entitled to refund
- SEPARATE_PRODUCT: The customer purchased separate products or services
- AUTHENTIC_PRODUCT: The product is not damaged, defective or counterfeit
- OTHER_REASONS: Other reasons for challenging
Explanation of why refund is refused.
Merchant information.
Seller name.
Store name.
Store physical address.
Store URL.
The stage when evidence is submitted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK.
The file unique identifiers of support documents.
The file IDs of customer communication. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of customer signature. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
List of documents.
Additional file descriptions or explanations.
File unique identifiers of the documents.
Type of the documents. Possible values: PRIMARY, ORDER, CUSTOMER, OTHER.
- PRIMARY: The primary evidence depends on the challenge reason.
- ORDER: Order related evidence.
- CUSTOMER: Customer related evidence.
- OTHER: Other supporting evidence.
The file IDs of duplicate payment evidence. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file unique identifiers of the files generated by Airwallex automatically based on text evidence or refund information.
The list of file IDs of other documents.
Deprecated. Use documents instead.
The file IDs of proof of delivery. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the receipt. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the refund policy. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
Time at which this PaymentDispute was created.
PaymentDispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
PaymentDispute due date.
PaymentDispute unique identifier.
The issuer’s comment on PaymentDispute.
The issuer’s documents on PaymentDispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
PaymentDispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
PaymentAttempt unique identifier.
PaymentIntent unique identifier.
The payment method type of original payment.
PaymentDispute reason.
PaymentDispute reason description.
PaymentDispute reason code.
PaymentDispute reason type. Possible values: CREDIT_NOT_PROCESSED, FRAUDULENT, DUPLICATE_CHARGE, PRODUCT_NOT_RECEIVED, PRODUCT_UNACCEPTABLE, UNRECOGNIZED_CHARGE, CANCELLED_PRODUCT, MISREPRESENTATION, COUNTERFEIT_PRODUCT, PROCESSING_ERRORS, AUTHORIZATION, NOT_RECOGNIZED, BANK_REJECTION, FUND_REVERSAL, CONSUMER_DISPUTE, POINT_OF_INTERACTION_ERROR and UNKNOWN.
The Refunds of original payment.
The acquirer reference number of Refund.
Refund unique identifier.
PaymentDispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
PaymentDispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the PaymentDispute.
- Applicable when receive notification from card schemes that PaymentDispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the PaymentDispute.
- Applicable when you challenge the PaymentDispute. At
PRE_CHARGEBACKstage, the issuing bank will escalate to the chargeback stage in the following days. AtRFI,CHARGEBACK, andPRE_ARBITRATIONstage, the issuing bank will review your submitted evidence and decide whether to escalate the PaymentDispute or not.
- Applicable when you challenge the PaymentDispute. At
- ACCEPTED: In this status the PaymentDispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the PaymentDispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the PaymentDispute at
- REVERSED: In this status, the PaymentDispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the PaymentDispute decision in your favor. No further action is required.
- Applicable at
CHARGEBACK,PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- LOST: In this status, the issuing bank has not accepted the evidence provided by you, or card schemes have ruled the PaymentDispute decision in Issuer’s favor. No further action is required.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- PENDING_CLOSURE: In this status, the issuing bank has escalated the PaymentDispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the PaymentDispute. Airwallex will decide whether to accept the PaymentDispute or respond to it on your behalf and may reach out to you for more information.- Applicable at
PRE_ARBITRATIONstage.
- Applicable at
- EXPIRED: In this status, the
RFIevent has expired as you have not responded to the request within 15 days.- Applicable at
RFIstage.
- Applicable at
- PENDING_DECISION: In this status, we have responded to the issuing bank with evidence provided by you. The issuing bank will review your submitted evidence and decide whether to accept the PaymentDispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this PaymentDispute was updated or operated on.
The BASE 64 encoded resource unique identifier of last PaymentDispute in items and navigation direction. When used in request, the response contains the page of PaymentDispute after it.
The BASE 64 encoded resource unique identifier of first PaymentDispute in items and navigation direction. When used in request, the response contains the page of PaymentDispute before it.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 403 | Forbidden |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api-demo.airwallex.com/api/v1/pa/payment_disputes' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "items": [3 {4 "id": "dst_hkpdw2eqp9oie",5 "stage": "CHARGEBACK",6 "status": "ACCEPTED",7 "mode": "COLLABORATION",8 "issuer_comment": "",9 "issuer_documents": [],10 "amount": 100,11 "currency": "USD",12 "merchant_order_id": "D202503210001",13 "payment_intent_id": "int_hkpdskz7vg1xc7uscdj",14 "payment_attempt_id": "att_hkpdw2eqp9oie",15 "acquirer_reference_number": "T1234567890",16 "payment_method_type": "VISA",17 "card_brand": "visa",18 "reason": {19 "original_code": "4837",20 "description": "Fraudulent transaction",21 "type": "FRAUDULENT"22 },23 "accept_details": [24 {25 "stage": "CHARGEBACK",26 "reason": "AGREEMENT_REACHED_WITH_CUSTOMER",27 "description": "Accepted",28 "refund": {29 "amount": 100,30 "reason": "REQUESTED_BY_CUSTOMER"31 },32 "accepted_by": "airwallex",33 "accepted_at": "2023-10-01T10:00:00+0000"34 }35 ],36 "challenge_details": [],37 "due_at": "2023-11-01T10:00:00+0000",38 "created_at": "2023-10-01T10:00:00+0000",39 "updated_at": "2023-10-01T10:00:00+0000",40 "transaction_type": "PAYMENT",41 "customer_name": "John Doe"42 }43 ]44}
Accept a PaymentDispute
POST /api/v1/pa/payment_disputes/{id}/accept
Accept a PaymentDispute. When a PaymentDispute is under status REQUIRES_RESPONSE, you can accept it to avoid further escalation and fees. Accepting the dispute during RFI stage will trigger a full refund. The refund amount and reason can be customized by populating the refund field.
PaymentDispute unique identifier.
Unique request identifier specified by the merchant.
User unique identifier of person/system accepts PaymentDispute.
The accept description.
The accept reason, OTHERS is used by default. One of
AGREEMENT_REACHED_WITH_CUSTOMERCUSTOMER_RELATIONSHIP_MAINTENANCELOW_VALUE_TRANSACTIONVALID_CUSTOMER_DISPUTECOLLABORATION_ACCEPTED_MANUALOTHERS
The Refund to be created. It is applicable when accepting a dispute at the RFI stage.
The refund amount when accepting RFI. If not specified, it will be same as the remaining amount that has been captured but not yet refunded. Please refer to supported currencies for supported minor units.
The refund reason when accepting RFI. OTHERS is used by default. One of REQUESTED_BY_CUSTOMER, DUPLICATE, FRAUDULENT, ABANDONED, and OTHERS
Further details on why the client is accepting the PaymentDispute event.
The time when the user accepted the PaymentDispute.
User unique identifier of person/system actioned on case.
The accept description.
The accept reason. One of
AGREEMENT_REACHED_WITH_CUSTOMERCUSTOMER_RELATIONSHIP_MAINTENANCELOW_VALUE_TRANSACTIONVALID_CUSTOMER_DISPUTENO_ACTION_TAKEN_BY_MERCHANTRDR_AUTO_ACCEPTEDCOLLABORATION_ACCEPTED_MANUALCOLLABORATION_AUTO_ACCEPTEDCOLLABORATION_AUTO_ACCEPTED_BY_EXPIRYOTHERS
The Refund requested to be created.
The refund amount when accepting RFI. If not specified, it will be same as the remaining amount that has been captured but not yet refunded. Please refer to supported currencies for supported minor units.
The refund reason when accepting RFI. OTHERS is used by default. One of REQUESTED_BY_CUSTOMER, DUPLICATE, FRAUDULENT, ABANDONED, and OTHERS
The stage when dispute is accepted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION.
The acquirer reference number of original payment.
Information about AI dispute automation, including recommendation and current status. Applicable only when the stage is CHARGEBACK.
The AI recommendation for the dispute, present when status is AVAILABLE.
The recommended action. Possible values: Challenge, Accept.
The evidence fields listed below are recommended for challenging this dispute.
For field definitions and accepted values,
refer to the evidence object in Challenge a PaymentDispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
PaymentDispute amount.
The card brand of original payment, applicable when payment_method_type is CARD. Possible values: visa, mastercard, maestro, union pay, american express, jcb, diners club international and discover.
The challenge data submitted at each stage.
The method used to challenge the dispute. Possible values:
- AI_DISPUTE_AUTOMATION: Challenge via AI Dispute Automation
- Applicable when PaymentDispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when PaymentDispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges PaymentDispute.
User unique identifier of person/system challenges PaymentDispute.
Customer information.
Customer billing address.
Customer device unique identifier.
Customer email.
Customer ip.
Customer name.
Customer phone number.
The delivery information.
The shipping address. Applicable at stage RFI.
The date when services or goods are delivered.
The amount of shipping fee. Applicable at stage RFI.
The currency of shipping fee. Applicable at stage RFI.
The recipient's name. Applicable at stage RFI.
The recipient's phone number. Applicable at stage RFI.
The shipping date (the expected delivery date for RFI).
The company name managing this delivery, such as asendia-usa, 4px, and so on.
The shipping method, such as Priority Mail, Flat rate, and so on. Applicable at stage RFI.
The shipping status, such as SHIPPED, DELIVERED, and so on. Applicable at stage RFI.
The shipping tracking number.
The evidence submitted when challenge_method is AI_DISPUTE_AUTOMATION.
File unique identifiers of access activity files. Provide screenshots from your activity log that show the customer's on-site behaviour, such as login times or download timestamps. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of authenticity proof files. Provide documentation that confirms your products are genuine and not counterfeit. This can include certificates, supplier invoices, or brand authorization letters. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of customer communication files. Provide copies of any emails, chat logs, or messages with the customer that show communication before or after the purchase. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Acquirer reference number of the duplicate transaction.
Explanation of the duplicate transaction.
File unique identifiers of duplicate payment files. Provide documents that show how this transaction differs from any potential duplicates. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Amount and currency of the duplicate transaction.
Creation date of the duplicate transaction.
Description of the merchant's business model.
Date and time when the order was fulfilled.
File unique identifiers of order fulfillment files. Provide screenshots of delivery confirmation or shipment tracking information that clearly show the order was successfully delivered. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of order snapshot files. Provide screenshots of the customer's receipt or order confirmation page as evidence that the customer placed the order. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous won disputes on same card. Provide evidence of any previous disputes that you won for transactions using the same card. This helps establish a history of legitimate transactions. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous purchases of similar products. Provide proof of the customer's past purchases of similar items to show their history and relationship with your business. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of product usage files. Provide evidence that the customer has used the product or service, such as a login record or usage timestamp. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Description of the product.
File unique identifiers of product snapshot files. Provide a screenshot of the product page or a photo of the item to show that the product matches its description. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers for your refund policy documents. Upload all documents that describe your refund policy. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
URL of the refund policy page.
File unique identifiers of user agreement files. Upload your user agreement forms that outline the terms and conditions for your customers. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
The order information. Applicable when the stage is RFI.
Time at which this order was created.
The order unique identifier.
The invoice number of order.
The products of order.
Product category at the merchant store, such as home furnishings, pet supplies, apparel and accessories
Merchant’s product identifier code. Maximum of 128 characters.
Product description. Maximum of 500 characters.
The effective end time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The effective start time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The preview image url for this product, which is usually displayed as thumbnail in the order details.
Name of the product. Maximum of 255 characters.
Product quantity
Seller info of the purchase order
The identifier of the seller in the merchant's system
The name of the seller in the merchant's system
Stock keeping unit. A unique identifier assigned by the merchant to identify and track this specific product. Maximum of 128 characters.
Type of product, such as physical_good, intangible_good, or service. Maximum of 128 characters.
Product unit price
The url that links to the product page at merchant site.
The total amount of order.
The currency of total amount.
The description of product.
The type of Product.
The reason why the merchant challenges the dispute. Possible values:
- CUSTOMER_WITHDRAWN: The customer withdrew the dispute
- CUSTOMER_REFUNDED: The customer has already been refunded
- PRODUCT_RECEIVED: The customer has already received / will receive the product or service
- PURCHASE_HISTORY: The customer has a purchasing history with me
- NOT_ENTITLED: The customer is not entitled to refund
- SEPARATE_PRODUCT: The customer purchased separate products or services
- AUTHENTIC_PRODUCT: The product is not damaged, defective or counterfeit
- OTHER_REASONS: Other reasons for challenging
Explanation of why refund is refused.
Merchant information.
Seller name.
Store name.
Store physical address.
Store URL.
The stage when evidence is submitted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK.
The file unique identifiers of support documents.
The file IDs of customer communication. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of customer signature. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
List of documents.
Additional file descriptions or explanations.
File unique identifiers of the documents.
Type of the documents. Possible values: PRIMARY, ORDER, CUSTOMER, OTHER.
- PRIMARY: The primary evidence depends on the challenge reason.
- ORDER: Order related evidence.
- CUSTOMER: Customer related evidence.
- OTHER: Other supporting evidence.
The file IDs of duplicate payment evidence. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file unique identifiers of the files generated by Airwallex automatically based on text evidence or refund information.
The list of file IDs of other documents.
Deprecated. Use documents instead.
The file IDs of proof of delivery. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the receipt. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the refund policy. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
Time at which this PaymentDispute was created.
PaymentDispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
PaymentDispute due date.
PaymentDispute unique identifier.
The issuer’s comment on PaymentDispute.
The issuer’s documents on PaymentDispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
PaymentDispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
PaymentAttempt unique identifier.
PaymentIntent unique identifier.
The payment method type of original payment.
PaymentDispute reason.
PaymentDispute reason description.
PaymentDispute reason code.
PaymentDispute reason type. Possible values: CREDIT_NOT_PROCESSED, FRAUDULENT, DUPLICATE_CHARGE, PRODUCT_NOT_RECEIVED, PRODUCT_UNACCEPTABLE, UNRECOGNIZED_CHARGE, CANCELLED_PRODUCT, MISREPRESENTATION, COUNTERFEIT_PRODUCT, PROCESSING_ERRORS, AUTHORIZATION, NOT_RECOGNIZED, BANK_REJECTION, FUND_REVERSAL, CONSUMER_DISPUTE, POINT_OF_INTERACTION_ERROR and UNKNOWN.
The Refunds of original payment.
The acquirer reference number of Refund.
Refund unique identifier.
PaymentDispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
PaymentDispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the PaymentDispute.
- Applicable when receive notification from card schemes that PaymentDispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the PaymentDispute.
- Applicable when you challenge the PaymentDispute. At
PRE_CHARGEBACKstage, the issuing bank will escalate to the chargeback stage in the following days. AtRFI,CHARGEBACK, andPRE_ARBITRATIONstage, the issuing bank will review your submitted evidence and decide whether to escalate the PaymentDispute or not.
- Applicable when you challenge the PaymentDispute. At
- ACCEPTED: In this status the PaymentDispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the PaymentDispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the PaymentDispute at
- REVERSED: In this status, the PaymentDispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the PaymentDispute decision in your favor. No further action is required.
- Applicable at
CHARGEBACK,PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- LOST: In this status, the issuing bank has not accepted the evidence provided by you, or card schemes have ruled the PaymentDispute decision in Issuer’s favor. No further action is required.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- PENDING_CLOSURE: In this status, the issuing bank has escalated the PaymentDispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the PaymentDispute. Airwallex will decide whether to accept the PaymentDispute or respond to it on your behalf and may reach out to you for more information.- Applicable at
PRE_ARBITRATIONstage.
- Applicable at
- EXPIRED: In this status, the
RFIevent has expired as you have not responded to the request within 15 days.- Applicable at
RFIstage.
- Applicable at
- PENDING_DECISION: In this status, we have responded to the issuing bank with evidence provided by you. The issuing bank will review your submitted evidence and decide whether to accept the PaymentDispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this PaymentDispute was updated or operated on.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 403 | Forbidden |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api-demo.airwallex.com/api/v1/pa/payment_disputes/dst_hkpdw2eqp9oie/accept' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "accepted_by": "airwallex",> "description": "Accepted",> "reason": "AGREEMENT_REACHED_WITH_CUSTOMER",> "request_id": "dd9a28c6-ef7b-44fe-b845-db487bf401c5",> "refund": {> "amount": 100,> "reason": "REQUESTED_BY_CUSTOMER"> }>}'
1{2 "id": "dst_hkpdw2eqp9oie",3 "stage": "CHARGEBACK",4 "status": "ACCEPTED",5 "amount": 100,6 "currency": "USD",7 "mode": "COLLABORATION",8 "merchant_order_id": "D202503210001",9 "payment_intent_id": "int_hkpdskz7vg1xc7uscdj",10 "payment_attempt_id": "att_hkpdw2eqp9oie",11 "acquirer_reference_number": "T1234567890",12 "payment_method_type": "VISA",13 "issuer_comment": "",14 "issuer_documents": [],15 "card_brand": "visa",16 "reason": {17 "original_code": "4837",18 "description": "Fraudulent transaction",19 "type": "FRAUDULENT"20 },21 "accept_details": [22 {23 "stage": "CHARGEBACK",24 "reason": "AGREEMENT_REACHED_WITH_CUSTOMER",25 "description": "Accepted",26 "refund": {27 "amount": 100,28 "reason": "REQUESTED_BY_CUSTOMER"29 },30 "accepted_by": "airwallex",31 "accepted_at": "2023-10-01T10:00:00+0000"32 }33 ],34 "challenge_details": [],35 "due_at": "2023-11-01T10:00:00+0000",36 "transaction_type": "PAYMENT",37 "customer_name": "John Doe",38 "created_at": "2023-10-01T10:00:00+0000",39 "updated_at": "2023-10-01T10:00:00+0000"40}
Challenge a PaymentDispute
POST /api/v1/pa/payment_disputes/{id}/challenge
Challenge a PaymentDispute. When you receive a PaymentDispute in Chargeback or RFI stage with REQUIRES_RESPONSE status then you can further challenge the PaymentDispute. Challenge response should include at least one of the recommended evidence document types attached, please use File Service to upload files and refer to it under supporting_documents. There are different suggested information sections in different stages, please check if the section is applicable before submission.
PaymentDispute unique identifier.
Unique request identifier specified by the merchant.
The method used to challenge the dispute. Possible values:
- AI_DISPUTE_AUTOMATION: Challenge using AI Dispute Automation
- Applicable when PaymentDispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when PaymentDispute stage is
- STANDARD: Challenge using standard flow
Default to STANDARD if not provided.
User unique identifier of person/system challenges PaymentDispute.
Customer information. Applicable when PaymentDispute stage is CHARGEBACK.
Customer billing address.
Customer device unique identifier.
Customer email.
Customer ip.
Customer name.
Customer phone number.
The delivery information of goods or services.
The shipping address. Applicable at stage RFI.
The date when services or goods are delivered.
The amount of shipping fee. Applicable at stage RFI. Please refer to supported currencies for supported minor units.
The currency of shipping fee. Applicable at stage RFI. Please refer to supported currencies .
The recipient's name. Applicable at stage RFI.
The recipient's phone number. Applicable at stage RFI.
The shipping date (the expected delivery date for RFI).
The company name managing this delivery, such as asendia-usa, 4px, and so on.
The shipping method, such as Priority Mail, Flat rate, and so on. Applicable at stage RFI.
The shipping status, such as SHIPPED, DELIVERED, and so on. Applicable at stage RFI.
The shipping tracking number.
The additional description of the PaymentDispute.
Deprecated. Use supporting_documents.documents.description instead.
The defense information when a PaymentDispute is raised due to a duplicate charge.
The explanation of duplicate payment.
The unique identifier of duplicate payment.
Evidence required when challenge_method is set to AI_DISPUTE_AUTOMATION.
File unique identifiers of access activity files. Provide screenshots from your activity log that show the customer's on-site behaviour, such as login times or download timestamps. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of authenticity proof files. Provide documentation that confirms your products are genuine and not counterfeit. This can include certificates, supplier invoices, or brand authorization letters. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of customer communication files. Provide copies of any emails, chat logs, or messages with the customer that show communication before or after the purchase. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Acquirer reference number of the duplicate transaction.
Explanation of the duplicate transaction.
File unique identifiers of duplicate payment files. Provide documents that show how this transaction differs from any potential duplicates. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Amount and currency of the duplicate transaction.
Creation date of the duplicate transaction.
Description of the merchant's business model.
Date and time when the order was fulfilled.
File unique identifiers of order fulfillment files. Provide screenshots of delivery confirmation or shipment tracking information that clearly show the order was successfully delivered. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of order snapshot files. Provide screenshots of the customer's receipt or order confirmation page as evidence that the customer placed the order. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous won disputes on same card. Provide evidence of any previous disputes that you won for transactions using the same card. This helps establish a history of legitimate transactions. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous purchases of similar products. Provide proof of the customer's past purchases of similar items to show their history and relationship with your business. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of product usage files. Provide evidence that the customer has used the product or service, such as a login record or usage timestamp. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Description of the product.
File unique identifiers of product snapshot files. Provide a screenshot of the product page or a photo of the item to show that the product matches its description. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers for your refund policy documents. Upload all documents that describe your refund policy. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
URL of the refund policy page.
File unique identifiers of user agreement files. Upload your user agreement forms that outline the terms and conditions for your customers. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
The order information. Applicable when PaymentDispute stage is RFI.
Time at which this order was created.
The order unique identifier.
The invoice number of order.
The products of order.
Product category at the merchant store, such as home furnishings, pet supplies, apparel and accessories
Merchant’s product identifier code. Maximum of 128 characters.
Product description. Maximum of 500 characters.
The effective end time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The effective start time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The preview image url for this product, which is usually displayed as thumbnail in the order details.
Name of the product. Maximum of 255 characters.
Product quantity
Seller info of the purchase order
The identifier of the seller in the merchant's system
The name of the seller in the merchant's system
Stock keeping unit. A unique identifier assigned by the merchant to identify and track this specific product. Maximum of 128 characters.
Type of product, such as physical_good, intangible_good, or service. Maximum of 128 characters.
Product unit price
The url that links to the product page at merchant site.
The total amount of order. Please refer to supported currencies for supported minor units.
The currency of total amount in 3-letter ISO 4217 currency code. Please refer to supported currencies .
The description of the product. Applicable when the PaymentDispute stage is CHARGEBACK.
The type of the product. Possible values: PHYSICAL_GOODS, DIGITAL_PRODUCT_OR_SERVICE, OFFLINE_SERVICE, TRAVEL, RESERVE_OR_BOOKING, OTHERS. Required when the PaymentDispute stage is CHARGEBACK.
The reason why the merchant challenges the dispute. Possible values:
- CUSTOMER_WITHDRAWN: The customer withdrew the dispute
- CUSTOMER_REFUNDED: The customer has already been refunded
- PRODUCT_RECEIVED: The customer has already received / will receive the product or service
- PURCHASE_HISTORY: The customer has a purchasing history with me
- NOT_ENTITLED: The customer is not entitled to refund
- SEPARATE_PRODUCT: The customer purchased separate products or services
- AUTHENTIC_PRODUCT: The product is not damaged, defective or counterfeit
- OTHER_REASONS: Other reasons for challenging
Explanation of why refund is refused. Applicable when PaymentDispute stage is CHARGEBACK.
Seller information. Applicable when PaymentDispute stage is RFI.
Seller name.
Store name.
Store physical address.
Store URL.
The file unique identifiers of support documents.
The file IDs of customer communication. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of customer signature. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
List of documents.
Additional file descriptions or explanations.
File unique identifiers of the documents.
Type of the documents. Possible values: PRIMARY, ORDER, CUSTOMER, OTHER.
- PRIMARY: The primary evidence depends on the challenge reason.
- ORDER: Order related evidence.
- CUSTOMER: Customer related evidence.
- OTHER: Other supporting evidence.
The file IDs of duplicate payment evidence. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The list of file IDs of other documents.
Deprecated. Use documents instead.
The file IDs of proof of delivery. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the receipt. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the refund policy. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
Further details on why the client is accepting the PaymentDispute event.
The time when the user accepted the PaymentDispute.
User unique identifier of person/system actioned on case.
The accept description.
The accept reason. One of
AGREEMENT_REACHED_WITH_CUSTOMERCUSTOMER_RELATIONSHIP_MAINTENANCELOW_VALUE_TRANSACTIONVALID_CUSTOMER_DISPUTENO_ACTION_TAKEN_BY_MERCHANTRDR_AUTO_ACCEPTEDCOLLABORATION_ACCEPTED_MANUALCOLLABORATION_AUTO_ACCEPTEDCOLLABORATION_AUTO_ACCEPTED_BY_EXPIRYOTHERS
The Refund requested to be created.
The refund amount when accepting RFI. If not specified, it will be same as the remaining amount that has been captured but not yet refunded. Please refer to supported currencies for supported minor units.
The refund reason when accepting RFI. OTHERS is used by default. One of REQUESTED_BY_CUSTOMER, DUPLICATE, FRAUDULENT, ABANDONED, and OTHERS
The stage when dispute is accepted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION.
The acquirer reference number of original payment.
Information about AI dispute automation, including recommendation and current status. Applicable only when the stage is CHARGEBACK.
The AI recommendation for the dispute, present when status is AVAILABLE.
The recommended action. Possible values: Challenge, Accept.
The evidence fields listed below are recommended for challenging this dispute.
For field definitions and accepted values,
refer to the evidence object in Challenge a PaymentDispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
PaymentDispute amount.
The card brand of original payment, applicable when payment_method_type is CARD. Possible values: visa, mastercard, maestro, union pay, american express, jcb, diners club international and discover.
The challenge data submitted at each stage.
The method used to challenge the dispute. Possible values:
- AI_DISPUTE_AUTOMATION: Challenge via AI Dispute Automation
- Applicable when PaymentDispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when PaymentDispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges PaymentDispute.
User unique identifier of person/system challenges PaymentDispute.
Customer information.
Customer billing address.
Customer device unique identifier.
Customer email.
Customer ip.
Customer name.
Customer phone number.
The delivery information.
The shipping address. Applicable at stage RFI.
The date when services or goods are delivered.
The amount of shipping fee. Applicable at stage RFI.
The currency of shipping fee. Applicable at stage RFI.
The recipient's name. Applicable at stage RFI.
The recipient's phone number. Applicable at stage RFI.
The shipping date (the expected delivery date for RFI).
The company name managing this delivery, such as asendia-usa, 4px, and so on.
The shipping method, such as Priority Mail, Flat rate, and so on. Applicable at stage RFI.
The shipping status, such as SHIPPED, DELIVERED, and so on. Applicable at stage RFI.
The shipping tracking number.
The evidence submitted when challenge_method is AI_DISPUTE_AUTOMATION.
File unique identifiers of access activity files. Provide screenshots from your activity log that show the customer's on-site behaviour, such as login times or download timestamps. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of authenticity proof files. Provide documentation that confirms your products are genuine and not counterfeit. This can include certificates, supplier invoices, or brand authorization letters. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of customer communication files. Provide copies of any emails, chat logs, or messages with the customer that show communication before or after the purchase. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Acquirer reference number of the duplicate transaction.
Explanation of the duplicate transaction.
File unique identifiers of duplicate payment files. Provide documents that show how this transaction differs from any potential duplicates. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Amount and currency of the duplicate transaction.
Creation date of the duplicate transaction.
Description of the merchant's business model.
Date and time when the order was fulfilled.
File unique identifiers of order fulfillment files. Provide screenshots of delivery confirmation or shipment tracking information that clearly show the order was successfully delivered. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of order snapshot files. Provide screenshots of the customer's receipt or order confirmation page as evidence that the customer placed the order. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous won disputes on same card. Provide evidence of any previous disputes that you won for transactions using the same card. This helps establish a history of legitimate transactions. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous purchases of similar products. Provide proof of the customer's past purchases of similar items to show their history and relationship with your business. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of product usage files. Provide evidence that the customer has used the product or service, such as a login record or usage timestamp. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Description of the product.
File unique identifiers of product snapshot files. Provide a screenshot of the product page or a photo of the item to show that the product matches its description. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers for your refund policy documents. Upload all documents that describe your refund policy. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
URL of the refund policy page.
File unique identifiers of user agreement files. Upload your user agreement forms that outline the terms and conditions for your customers. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
The order information. Applicable when the stage is RFI.
Time at which this order was created.
The order unique identifier.
The invoice number of order.
The products of order.
Product category at the merchant store, such as home furnishings, pet supplies, apparel and accessories
Merchant’s product identifier code. Maximum of 128 characters.
Product description. Maximum of 500 characters.
The effective end time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The effective start time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The preview image url for this product, which is usually displayed as thumbnail in the order details.
Name of the product. Maximum of 255 characters.
Product quantity
Seller info of the purchase order
The identifier of the seller in the merchant's system
The name of the seller in the merchant's system
Stock keeping unit. A unique identifier assigned by the merchant to identify and track this specific product. Maximum of 128 characters.
Type of product, such as physical_good, intangible_good, or service. Maximum of 128 characters.
Product unit price
The url that links to the product page at merchant site.
The total amount of order.
The currency of total amount.
The description of product.
The type of Product.
The reason why the merchant challenges the dispute. Possible values:
- CUSTOMER_WITHDRAWN: The customer withdrew the dispute
- CUSTOMER_REFUNDED: The customer has already been refunded
- PRODUCT_RECEIVED: The customer has already received / will receive the product or service
- PURCHASE_HISTORY: The customer has a purchasing history with me
- NOT_ENTITLED: The customer is not entitled to refund
- SEPARATE_PRODUCT: The customer purchased separate products or services
- AUTHENTIC_PRODUCT: The product is not damaged, defective or counterfeit
- OTHER_REASONS: Other reasons for challenging
Explanation of why refund is refused.
Merchant information.
Seller name.
Store name.
Store physical address.
Store URL.
The stage when evidence is submitted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK.
The file unique identifiers of support documents.
The file IDs of customer communication. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of customer signature. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
List of documents.
Additional file descriptions or explanations.
File unique identifiers of the documents.
Type of the documents. Possible values: PRIMARY, ORDER, CUSTOMER, OTHER.
- PRIMARY: The primary evidence depends on the challenge reason.
- ORDER: Order related evidence.
- CUSTOMER: Customer related evidence.
- OTHER: Other supporting evidence.
The file IDs of duplicate payment evidence. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file unique identifiers of the files generated by Airwallex automatically based on text evidence or refund information.
The list of file IDs of other documents.
Deprecated. Use documents instead.
The file IDs of proof of delivery. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the receipt. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the refund policy. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
Time at which this PaymentDispute was created.
PaymentDispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
PaymentDispute due date.
PaymentDispute unique identifier.
The issuer’s comment on PaymentDispute.
The issuer’s documents on PaymentDispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
PaymentDispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
PaymentAttempt unique identifier.
PaymentIntent unique identifier.
The payment method type of original payment.
PaymentDispute reason.
PaymentDispute reason description.
PaymentDispute reason code.
PaymentDispute reason type. Possible values: CREDIT_NOT_PROCESSED, FRAUDULENT, DUPLICATE_CHARGE, PRODUCT_NOT_RECEIVED, PRODUCT_UNACCEPTABLE, UNRECOGNIZED_CHARGE, CANCELLED_PRODUCT, MISREPRESENTATION, COUNTERFEIT_PRODUCT, PROCESSING_ERRORS, AUTHORIZATION, NOT_RECOGNIZED, BANK_REJECTION, FUND_REVERSAL, CONSUMER_DISPUTE, POINT_OF_INTERACTION_ERROR and UNKNOWN.
The Refunds of original payment.
The acquirer reference number of Refund.
Refund unique identifier.
PaymentDispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
PaymentDispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the PaymentDispute.
- Applicable when receive notification from card schemes that PaymentDispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the PaymentDispute.
- Applicable when you challenge the PaymentDispute. At
PRE_CHARGEBACKstage, the issuing bank will escalate to the chargeback stage in the following days. AtRFI,CHARGEBACK, andPRE_ARBITRATIONstage, the issuing bank will review your submitted evidence and decide whether to escalate the PaymentDispute or not.
- Applicable when you challenge the PaymentDispute. At
- ACCEPTED: In this status the PaymentDispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the PaymentDispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the PaymentDispute at
- REVERSED: In this status, the PaymentDispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the PaymentDispute decision in your favor. No further action is required.
- Applicable at
CHARGEBACK,PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- LOST: In this status, the issuing bank has not accepted the evidence provided by you, or card schemes have ruled the PaymentDispute decision in Issuer’s favor. No further action is required.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- PENDING_CLOSURE: In this status, the issuing bank has escalated the PaymentDispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the PaymentDispute. Airwallex will decide whether to accept the PaymentDispute or respond to it on your behalf and may reach out to you for more information.- Applicable at
PRE_ARBITRATIONstage.
- Applicable at
- EXPIRED: In this status, the
RFIevent has expired as you have not responded to the request within 15 days.- Applicable at
RFIstage.
- Applicable at
- PENDING_DECISION: In this status, we have responded to the issuing bank with evidence provided by you. The issuing bank will review your submitted evidence and decide whether to accept the PaymentDispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this PaymentDispute was updated or operated on.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 403 | Forbidden |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api-demo.airwallex.com/api/v1/pa/payment_disputes/dst_hkpdw2eqp9oie/challenge' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "challenged_by": "airwallex",> "customer_info": {> "billing_address": "1460 Mission St.#02W101, San Francisco, CA 94103, US",> "device_id": "59ec5db9-399c-4043-9a6c-fcd1a48d99aa",> "email": "[email protected]",> "ip": "123.123.123.123",> "name": "John Doe",> "phone_number": "+1 1234567890"> },> "delivery_info": {> "address": "address",> "delivered_at": "2023-10-01T10:00:00Z",> "fee_amount": 0,> "fee_currency": "null",> "name": "null",> "phone_number": "null",> "shipped_at": "2023-10-01T10:00:00Z",> "shipping_company": "SF",> "shipping_method": "null",> "status": "null",> "tracking_number": "123456789"> },> "product_description": "product description",> "product_type": "OFFLINE_SERVICE",> "request_id": "0cb05018-7ccd-42fa-9a5b-7d5197b9fb15",> "supporting_documents": {> "documents": [> {> "type": "OTHER",> "file_ids": [> "MTRkYjkyZWYtZTBh12tvbmcsfCxFdmlkZW5jZV9Qcm92aWRlZF9Gb3JfMTc0NDE3Nzg4NzU3Ng"> ]> }> ]> }>}'
1{2 "id": "dst_hkpdw2eqp9oie",3 "stage": "CHARGEBACK",4 "status": "CHALLENGED",5 "amount": 100,6 "currency": "USD",7 "mode": "COLLABORATION",8 "merchant_order_id": "D202503210001",9 "payment_intent_id": "int_hkpdskz7vg1xc7uscdj",10 "payment_attempt_id": "att_hkpdw2eqp9oie",11 "acquirer_reference_number": "T1234567890",12 "payment_method_type": "VISA",13 "issuer_comment": "",14 "issuer_documents": [],15 "card_brand": "visa",16 "reason": {17 "original_code": "4837",18 "description": "Fraudulent transaction",19 "type": "FRAUDULENT"20 },21 "challenge_details": [22 {23 "stage": "CHARGEBACK",24 "product_type": "OFFLINE_SERVICE",25 "product_description": "product description",26 "customer_info": {27 "name": "John Doe",28 "email": "[email protected]",29 "ip": "123.123.123.123",30 "billing_address": "1460 Mission St.#02W101, San Francisco, CA 94103, US",31 "device_id": "59ec5db9-399c-4043-9a6c-fcd1a48d99aa",32 "phone_number": "+1 1234567890"33 },34 "delivery_info": {35 "shipped_at": "2023-10-01T10:00:00+0000",36 "delivered_at": "2023-10-01T10:00:00+0000",37 "address": "address",38 "shipping_company": "SF",39 "tracking_number": "123456789"40 },41 "supporting_documents": {42 "documents": [43 {44 "type": "OTHER",45 "file_ids": [46 "MTRkYjkyZWYtZTBh12tvbmcsfCxFdmlkZW5jZV9Qcm92aWRlZF9Gb3JfMTc0NDE3Nzg4NzU3Ng"47 ]48 }49 ]50 },51 "challenged_by": "airwallex",52 "challenged_at": "2023-10-01T10:00:00+0000",53 "reason": "Fraudulent transaction"54 }55 ],56 "due_at": "2023-11-01T10:00:00+0000",57 "transaction_type": "PAYMENT",58 "customer_name": "John Doe",59 "created_at": "2023-10-01T10:00:00+0000",60 "updated_at": "2023-10-01T10:00:00+0000"61}
Update a PaymentDispute
POST /api/v1/pa/payment_disputes/{id}/update
Update a PaymentDispute by ID. Currently only the metadata field can be updated.
PaymentDispute ID.
A set of key-value pairs attached to the dispute. Maximum 50 key-value pairs. Keys and values must not exceed 256 characters.
Further details on why the client is accepting the PaymentDispute event.
The time when the user accepted the PaymentDispute.
User unique identifier of person/system actioned on case.
The accept description.
The accept reason. One of
AGREEMENT_REACHED_WITH_CUSTOMERCUSTOMER_RELATIONSHIP_MAINTENANCELOW_VALUE_TRANSACTIONVALID_CUSTOMER_DISPUTENO_ACTION_TAKEN_BY_MERCHANTRDR_AUTO_ACCEPTEDCOLLABORATION_ACCEPTED_MANUALCOLLABORATION_AUTO_ACCEPTEDCOLLABORATION_AUTO_ACCEPTED_BY_EXPIRYOTHERS
The Refund requested to be created.
The refund amount when accepting RFI. If not specified, it will be same as the remaining amount that has been captured but not yet refunded. Please refer to supported currencies for supported minor units.
The refund reason when accepting RFI. OTHERS is used by default. One of REQUESTED_BY_CUSTOMER, DUPLICATE, FRAUDULENT, ABANDONED, and OTHERS
The stage when dispute is accepted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION.
The acquirer reference number of original payment.
Information about AI dispute automation, including recommendation and current status. Applicable only when the stage is CHARGEBACK.
The AI recommendation for the dispute, present when status is AVAILABLE.
The recommended action. Possible values: Challenge, Accept.
The evidence fields listed below are recommended for challenging this dispute.
For field definitions and accepted values,
refer to the evidence object in Challenge a PaymentDispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
PaymentDispute amount.
The card brand of original payment, applicable when payment_method_type is CARD. Possible values: visa, mastercard, maestro, union pay, american express, jcb, diners club international and discover.
The challenge data submitted at each stage.
The method used to challenge the dispute. Possible values:
- AI_DISPUTE_AUTOMATION: Challenge via AI Dispute Automation
- Applicable when PaymentDispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when PaymentDispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges PaymentDispute.
User unique identifier of person/system challenges PaymentDispute.
Customer information.
Customer billing address.
Customer device unique identifier.
Customer email.
Customer ip.
Customer name.
Customer phone number.
The delivery information.
The shipping address. Applicable at stage RFI.
The date when services or goods are delivered.
The amount of shipping fee. Applicable at stage RFI.
The currency of shipping fee. Applicable at stage RFI.
The recipient's name. Applicable at stage RFI.
The recipient's phone number. Applicable at stage RFI.
The shipping date (the expected delivery date for RFI).
The company name managing this delivery, such as asendia-usa, 4px, and so on.
The shipping method, such as Priority Mail, Flat rate, and so on. Applicable at stage RFI.
The shipping status, such as SHIPPED, DELIVERED, and so on. Applicable at stage RFI.
The shipping tracking number.
The evidence submitted when challenge_method is AI_DISPUTE_AUTOMATION.
File unique identifiers of access activity files. Provide screenshots from your activity log that show the customer's on-site behaviour, such as login times or download timestamps. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of authenticity proof files. Provide documentation that confirms your products are genuine and not counterfeit. This can include certificates, supplier invoices, or brand authorization letters. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of customer communication files. Provide copies of any emails, chat logs, or messages with the customer that show communication before or after the purchase. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Acquirer reference number of the duplicate transaction.
Explanation of the duplicate transaction.
File unique identifiers of duplicate payment files. Provide documents that show how this transaction differs from any potential duplicates. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Amount and currency of the duplicate transaction.
Creation date of the duplicate transaction.
Description of the merchant's business model.
Date and time when the order was fulfilled.
File unique identifiers of order fulfillment files. Provide screenshots of delivery confirmation or shipment tracking information that clearly show the order was successfully delivered. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of order snapshot files. Provide screenshots of the customer's receipt or order confirmation page as evidence that the customer placed the order. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous won disputes on same card. Provide evidence of any previous disputes that you won for transactions using the same card. This helps establish a history of legitimate transactions. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of previous purchases of similar products. Provide proof of the customer's past purchases of similar items to show their history and relationship with your business. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers of product usage files. Provide evidence that the customer has used the product or service, such as a login record or usage timestamp. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
Description of the product.
File unique identifiers of product snapshot files. Provide a screenshot of the product page or a photo of the item to show that the product matches its description. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
File unique identifiers for your refund policy documents. Upload all documents that describe your refund policy. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
URL of the refund policy page.
File unique identifiers of user agreement files. Upload your user agreement forms that outline the terms and conditions for your customers. Supported file formats: JPG, PNG, WEBP and max 10MB size. Please use File Service to upload files.
The order information. Applicable when the stage is RFI.
Time at which this order was created.
The order unique identifier.
The invoice number of order.
The products of order.
Product category at the merchant store, such as home furnishings, pet supplies, apparel and accessories
Merchant’s product identifier code. Maximum of 128 characters.
Product description. Maximum of 500 characters.
The effective end time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The effective start time of the product, only applicable when product type is intangible_good. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The preview image url for this product, which is usually displayed as thumbnail in the order details.
Name of the product. Maximum of 255 characters.
Product quantity
Seller info of the purchase order
The identifier of the seller in the merchant's system
The name of the seller in the merchant's system
Stock keeping unit. A unique identifier assigned by the merchant to identify and track this specific product. Maximum of 128 characters.
Type of product, such as physical_good, intangible_good, or service. Maximum of 128 characters.
Product unit price
The url that links to the product page at merchant site.
The total amount of order.
The currency of total amount.
The description of product.
The type of Product.
The reason why the merchant challenges the dispute. Possible values:
- CUSTOMER_WITHDRAWN: The customer withdrew the dispute
- CUSTOMER_REFUNDED: The customer has already been refunded
- PRODUCT_RECEIVED: The customer has already received / will receive the product or service
- PURCHASE_HISTORY: The customer has a purchasing history with me
- NOT_ENTITLED: The customer is not entitled to refund
- SEPARATE_PRODUCT: The customer purchased separate products or services
- AUTHENTIC_PRODUCT: The product is not damaged, defective or counterfeit
- OTHER_REASONS: Other reasons for challenging
Explanation of why refund is refused.
Merchant information.
Seller name.
Store name.
Store physical address.
Store URL.
The stage when evidence is submitted. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK.
The file unique identifiers of support documents.
The file IDs of customer communication. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of customer signature. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
List of documents.
Additional file descriptions or explanations.
File unique identifiers of the documents.
Type of the documents. Possible values: PRIMARY, ORDER, CUSTOMER, OTHER.
- PRIMARY: The primary evidence depends on the challenge reason.
- ORDER: Order related evidence.
- CUSTOMER: Customer related evidence.
- OTHER: Other supporting evidence.
The file IDs of duplicate payment evidence. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file unique identifiers of the files generated by Airwallex automatically based on text evidence or refund information.
The list of file IDs of other documents.
Deprecated. Use documents instead.
The file IDs of proof of delivery. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the receipt. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
The file IDs of the refund policy. Applicable when stage is CHARGEBACK.
Deprecated. Use documents instead.
Time at which this PaymentDispute was created.
PaymentDispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
PaymentDispute due date.
PaymentDispute unique identifier.
The issuer’s comment on PaymentDispute.
The issuer’s documents on PaymentDispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
PaymentDispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
PaymentAttempt unique identifier.
PaymentIntent unique identifier.
The payment method type of original payment.
PaymentDispute reason.
PaymentDispute reason description.
PaymentDispute reason code.
PaymentDispute reason type. Possible values: CREDIT_NOT_PROCESSED, FRAUDULENT, DUPLICATE_CHARGE, PRODUCT_NOT_RECEIVED, PRODUCT_UNACCEPTABLE, UNRECOGNIZED_CHARGE, CANCELLED_PRODUCT, MISREPRESENTATION, COUNTERFEIT_PRODUCT, PROCESSING_ERRORS, AUTHORIZATION, NOT_RECOGNIZED, BANK_REJECTION, FUND_REVERSAL, CONSUMER_DISPUTE, POINT_OF_INTERACTION_ERROR and UNKNOWN.
The Refunds of original payment.
The acquirer reference number of Refund.
Refund unique identifier.
PaymentDispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
PaymentDispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the PaymentDispute.
- Applicable when receive notification from card schemes that PaymentDispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the PaymentDispute.
- Applicable when you challenge the PaymentDispute. At
PRE_CHARGEBACKstage, the issuing bank will escalate to the chargeback stage in the following days. AtRFI,CHARGEBACK, andPRE_ARBITRATIONstage, the issuing bank will review your submitted evidence and decide whether to escalate the PaymentDispute or not.
- Applicable when you challenge the PaymentDispute. At
- ACCEPTED: In this status the PaymentDispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the PaymentDispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the PaymentDispute at
- REVERSED: In this status, the PaymentDispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that PaymentDispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the PaymentDispute decision in your favor. No further action is required.
- Applicable at
CHARGEBACK,PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- LOST: In this status, the issuing bank has not accepted the evidence provided by you, or card schemes have ruled the PaymentDispute decision in Issuer’s favor. No further action is required.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
- PENDING_CLOSURE: In this status, the issuing bank has escalated the PaymentDispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the PaymentDispute. Airwallex will decide whether to accept the PaymentDispute or respond to it on your behalf and may reach out to you for more information.- Applicable at
PRE_ARBITRATIONstage.
- Applicable at
- EXPIRED: In this status, the
RFIevent has expired as you have not responded to the request within 15 days.- Applicable at
RFIstage.
- Applicable at
- PENDING_DECISION: In this status, we have responded to the issuing bank with evidence provided by you. The issuing bank will review your submitted evidence and decide whether to accept the PaymentDispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this PaymentDispute was updated or operated on.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 403 | Forbidden |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api-demo.airwallex.com/api/v1/pa/payment_disputes/payment_dispute_id/update' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "metadata": {> "key": "value"> }>}'
1{2 "accept_details": [3 {4 "accepted_at": "2023-09-18T03:11:00+0000",5 "accepted_by": "[email protected]",6 "description": "ACCEPT",7 "reason": "ee939540-3203-4a2c-9172-89a566485dd9",8 "refund": {9 "amount": 10,10 "reason": "REQUESTED_BY_CUSTOMER"11 }12 }13 ],14 "acquirer_reference_number": "789456",15 "ai_dispute_automation": {16 "recommendation": {17 "action": "Challenge",18 "evidence_to_submit": [19 "order_snapshot_file_ids",20 "product_description",21 "merchant_business_model_description"22 ]23 },24 "status": "AVAILABLE",25 "unavailable_reason": "NOT_SUPPORTED"26 },27 "amount": 100,28 "card_brand": "visa",29 "challenge_details": [30 {31 "challenge_method": "AI_DISPUTE_AUTOMATION",32 "challenged_at": "2023-09-18T03:11:00+0000",33 "challenged_by": "[email protected]",34 "customer_info": {35 "billing_address": "Billing address",36 "device_id": "00000000-000000000000000",37 "email": "[email protected]",38 "ip": "212.121.222.123",39 "name": "John Deo",40 "phone_number": "13800000000"41 },42 "delivery_info": {43 "address": "Shipping address",44 "delivered_at": "2023-09-18T03:11:00+0000",45 "fee_amount": 10,46 "fee_currency": "USD",47 "name": "Joe Doe",48 "phone_number": "13800000000",49 "shipped_at": "2023-09-18T03:11:00+0000",50 "shipping_company": "Shipping company",51 "shipping_method": "Shipping method",52 "status": "SHIPPED",53 "tracking_number": "123456"54 },55 "evidence": {56 "access_activity_file_ids": [],57 "authenticity_proof_file_ids": [],58 "customer_communication_file_ids": [],59 "duplicate_payment_file_ids": [],60 "duplicate_transaction_amount_currency": "100.00 USD",61 "duplicate_transaction_created_at": "2024-01-15T10:30:00Z",62 "order_fulfilled_at": "2024-01-15T10:30:00Z",63 "order_fulfillment_file_ids": [],64 "order_snapshot_file_ids": [],65 "previous_dispute_won_on_same_card_file_ids": [],66 "previous_purchase_similar_product_file_ids": [],67 "product_consumption_file_ids": [],68 "product_description": "Digital subscription service",69 "product_snapshot_file_ids": [],70 "refund_policy_file_ids": [],71 "user_agreement_file_ids": []72 },73 "order_info": {74 "created_at": "2023-09-18T03:11:00+0000",75 "id": "123456",76 "invoice_number": "456123",77 "products": [78 {79 "category": "Apparel and accessories",80 "code": "3414314111",81 "desc": "IPHONE 7",82 "effective_end_at": "2020-12-31T23:59:59Z",83 "effective_start_at": "2020-01-01T00:00:00Z",84 "image_url": "https://example.airwallex.com/product/12345.png",85 "name": "IPHONE7",86 "quantity": 5,87 "sku": "100004",88 "type": "physical",89 "unit_price": 100.01,90 "url": "https://example.airwallex.com/product/12345"91 }92 ],93 "total_amount": 200,94 "total_currency": "USD"95 },96 "product_description": "product description",97 "product_type": "PHYSICAL_GOODS",98 "reason": "CUSTOMER_WITHDRAWN",99 "refund_refusal_reason": "reason",100 "seller_info": {101 "name": "seller",102 "store_name": "store",103 "store_physical_address": "store address",104 "store_url": "https://www.store-url.com"105 },106 "stage": "CHARGEBACK",107 "supporting_documents": {108 "customer_communication_documents": [109 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="110 ],111 "customer_signature_documents": [112 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="113 ],114 "documents": [115 {116 "description": "document descriptions",117 "file_ids": [118 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="119 ],120 "type": "PRIMARY"121 }122 ],123 "duplicate_charge_defense_documents": [124 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="125 ],126 "generated_files": [127 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="128 ],129 "other_documents": [130 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="131 ],132 "proof_of_delivery_documents": [133 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="134 ],135 "receipt_documents": [136 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="137 ],138 "refund_policy_documents": [139 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="140 ]141 }142 }143 ],144 "created_at": "2023-09-18T03:11:00+0000",145 "currency": "USD",146 "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",147 "customer_name": "John Doe",148 "due_at": "2023-09-18T03:11:00+0000",149 "id": "dst_nlstrf5jxgp32pfqbtq",150 "issuer_comment": "comment",151 "issuer_documents": [152 "YmVkODdkNGMtNWFiZC00MzM0LdGVzdC5wZGZfMTYxNTI2MDIxOQ=="153 ],154 "merchant_order_id": "123456",155 "metadata": {},156 "mode": "COLLABORATION",157 "payment_attempt_id": "att_nlstskcx5gipkzd6kse_dwsja0_decrp",158 "payment_intent_id": "int_nlstbs6rlgipjdwsja0_decrp",159 "payment_method_type": "VISA",160 "reason": {161 "description": "<string>",162 "original_code": "<string>",163 "type": "PRODUCT_NOT_RECEIVED"164 },165 "refunds": [166 {167 "acquirer_reference_number": "02709821210000001031868",168 "id": "rfd_ps8e0ZgQzd2QnCxVpzJrHD6KOVu"169 }170 ],171 "stage": "CHARGEBACK",172 "status": "RECEIVED",173 "transaction_type": "PAYMENT",174 "updated_at": "2023-09-18T03:11:00+0000"175}