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}/updatePOST /api/v1/pa/payment_disputes/{id}/acceptPOST /api/v1/pa/payment_disputes/{id}/challengeGET /api/v1/pa/payment_disputes/{id}/related_payment_intents
Retrieve a Payment Dispute
GET /api/v1/pa/payment_disputes/{id}
Retrieve Payment Dispute information using Payment Dispute unique identifier.
Payment Dispute unique identifier.
Further details on why the client is accepting the Payment Dispute event.
The time when the user accepted the Payment Dispute.
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 Payment Dispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
Payment Dispute 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 Payment Dispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when Payment Dispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges Payment Dispute.
User unique identifier of person/system challenges Payment Dispute.
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 Payment Dispute was created.
Payment Dispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
Payment Dispute due date.
Payment Dispute unique identifier.
The issuer’s comment on Payment Dispute.
The issuer’s documents on Payment Dispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
Payment Dispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
Payment Attempt unique identifier.
Payment Intent unique identifier.
The payment method type of original payment.
Payment Dispute reason.
Payment Dispute reason description.
Payment Dispute reason code.
Payment Dispute 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.
Payment Dispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
Payment Dispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the Payment Dispute.
- Applicable when receive notification from card schemes that Payment Dispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the Payment Dispute.
- Applicable when you challenge the Payment Dispute. 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 Payment Dispute or not.
- Applicable when you challenge the Payment Dispute. At
- ACCEPTED: In this status the Payment Dispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the Payment Dispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the Payment Dispute at
- REVERSED: In this status, the Payment Dispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the Payment Dispute 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 Payment Dispute 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 Payment Dispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the Payment Dispute. Airwallex will decide whether to accept the Payment Dispute 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 Payment Dispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this Payment Dispute 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.sandbox.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+00:00"32 }33 ],34 "challenge_details": [],35 "due_at": "2023-11-01T10:00:00+00:00",36 "transaction_type": "PAYMENT",37 "customer_name": "John Doe",38 "created_at": "2023-10-01T10:00:00+00:00",39 "updated_at": "2023-10-01T10:00:00+00:00"40}
List all Payment Disputes
GET /api/v1/pa/payment_disputes
List all Payment Disputes 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 timestamp must include an explicit timezone (e.g. Z or -04:00).
The start time of updated_at in ISO8601 format. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The order unique identifier of original payment.
0 or the BASE 64 encoded resource unique identifier of Payment Dispute and navigation direction to indicate the page should be returned. 0 is used by default for initial page
Payment Dispute status.
The payment method type of original payment.
Payment Dispute reason code.
Number of Payment Disputes to be listed per page. Default value is 10. Maximum is 1000. The value greater than the maximum will be capped to the maximum.
Payment Dispute stage.
Payment Dispute status.
The end time of created_at in ISO8601 format.
The end time of due_at in ISO8601 format. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The end time of updated_at in ISO8601 format. The timestamp must include an explicit timezone (e.g. Z or -04:00).
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
The list of Payment Disputes
Further details on why the client is accepting the Payment Dispute event.
The time when the user accepted the Payment Dispute.
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 Payment Dispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
Payment Dispute 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 Payment Dispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when Payment Dispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges Payment Dispute.
User unique identifier of person/system challenges Payment Dispute.
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 Payment Dispute was created.
Payment Dispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
Payment Dispute due date.
Payment Dispute unique identifier.
The issuer’s comment on Payment Dispute.
The issuer’s documents on Payment Dispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
Payment Dispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
Payment Attempt unique identifier.
Payment Intent unique identifier.
The payment method type of original payment.
Payment Dispute reason.
Payment Dispute reason description.
Payment Dispute reason code.
Payment Dispute 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.
Payment Dispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
Payment Dispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the Payment Dispute.
- Applicable when receive notification from card schemes that Payment Dispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the Payment Dispute.
- Applicable when you challenge the Payment Dispute. 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 Payment Dispute or not.
- Applicable when you challenge the Payment Dispute. At
- ACCEPTED: In this status the Payment Dispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the Payment Dispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the Payment Dispute at
- REVERSED: In this status, the Payment Dispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the Payment Dispute 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 Payment Dispute 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 Payment Dispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the Payment Dispute. Airwallex will decide whether to accept the Payment Dispute 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 Payment Dispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this Payment Dispute was updated or operated on.
The BASE 64 encoded resource unique identifier of last Payment Dispute in items and navigation direction. When used in request, the response contains the page of Payment Dispute after it.
The BASE 64 encoded resource unique identifier of first Payment Dispute in items and navigation direction. When used in request, the response contains the page of Payment Dispute 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.sandbox.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+00:00"34 }35 ],36 "challenge_details": [],37 "due_at": "2023-11-01T10:00:00+00:00",38 "created_at": "2023-10-01T10:00:00+00:00",39 "updated_at": "2023-10-01T10:00:00+00:00",40 "transaction_type": "PAYMENT",41 "customer_name": "John Doe"42 }43 ]44}
Update a Payment Dispute
POST /api/v1/pa/payment_disputes/{id}/update
Update a Payment Dispute by ID. Currently only the metadata field can be updated.
Payment Dispute 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 Payment Dispute event.
The time when the user accepted the Payment Dispute.
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 Payment Dispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
Payment Dispute 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 Payment Dispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when Payment Dispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges Payment Dispute.
User unique identifier of person/system challenges Payment Dispute.
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 Payment Dispute was created.
Payment Dispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
Payment Dispute due date.
Payment Dispute unique identifier.
The issuer’s comment on Payment Dispute.
The issuer’s documents on Payment Dispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
Payment Dispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
Payment Attempt unique identifier.
Payment Intent unique identifier.
The payment method type of original payment.
Payment Dispute reason.
Payment Dispute reason description.
Payment Dispute reason code.
Payment Dispute 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.
Payment Dispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
Payment Dispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the Payment Dispute.
- Applicable when receive notification from card schemes that Payment Dispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the Payment Dispute.
- Applicable when you challenge the Payment Dispute. 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 Payment Dispute or not.
- Applicable when you challenge the Payment Dispute. At
- ACCEPTED: In this status the Payment Dispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the Payment Dispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the Payment Dispute at
- REVERSED: In this status, the Payment Dispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the Payment Dispute 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 Payment Dispute 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 Payment Dispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the Payment Dispute. Airwallex will decide whether to accept the Payment Dispute 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 Payment Dispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this Payment Dispute 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.sandbox.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+00:00",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+00:00",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+00:00",45 "fee_amount": 10,46 "fee_currency": "USD",47 "name": "Joe Doe",48 "phone_number": "13800000000",49 "shipped_at": "2023-09-18T03:11:00+00:00",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+00:00",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+00:00",145 "currency": "USD",146 "customer_id": "cus_ps8e0ZgQzd2QnCxVpzJrHD6KOVu",147 "customer_name": "John Doe",148 "due_at": "2023-09-18T03:11:00+00:00",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+00:00"175}
Accept a Payment Dispute
POST /api/v1/pa/payment_disputes/{id}/accept
Accept a Payment Dispute. When a Payment Dispute 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.
Payment Dispute unique identifier.
Unique request identifier specified by the merchant.
User unique identifier of person/system accepts Payment Dispute.
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 Payment Dispute event.
The time when the user accepted the Payment Dispute.
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 Payment Dispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
Payment Dispute 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 Payment Dispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when Payment Dispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges Payment Dispute.
User unique identifier of person/system challenges Payment Dispute.
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 Payment Dispute was created.
Payment Dispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
Payment Dispute due date.
Payment Dispute unique identifier.
The issuer’s comment on Payment Dispute.
The issuer’s documents on Payment Dispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
Payment Dispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
Payment Attempt unique identifier.
Payment Intent unique identifier.
The payment method type of original payment.
Payment Dispute reason.
Payment Dispute reason description.
Payment Dispute reason code.
Payment Dispute 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.
Payment Dispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
Payment Dispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the Payment Dispute.
- Applicable when receive notification from card schemes that Payment Dispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the Payment Dispute.
- Applicable when you challenge the Payment Dispute. 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 Payment Dispute or not.
- Applicable when you challenge the Payment Dispute. At
- ACCEPTED: In this status the Payment Dispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the Payment Dispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the Payment Dispute at
- REVERSED: In this status, the Payment Dispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the Payment Dispute 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 Payment Dispute 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 Payment Dispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the Payment Dispute. Airwallex will decide whether to accept the Payment Dispute 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 Payment Dispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this Payment Dispute 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.sandbox.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+00:00"32 }33 ],34 "challenge_details": [],35 "due_at": "2023-11-01T10:00:00+00:00",36 "transaction_type": "PAYMENT",37 "customer_name": "John Doe",38 "created_at": "2023-10-01T10:00:00+00:00",39 "updated_at": "2023-10-01T10:00:00+00:00"40}
Challenge a Payment Dispute
POST /api/v1/pa/payment_disputes/{id}/challenge
Challenge a Payment Dispute. When you receive a Payment Dispute in Chargeback or RFI stage with REQUIRES_RESPONSE status then you can further challenge the Payment Dispute. 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.
Payment Dispute 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 Payment Dispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when Payment Dispute stage is
- STANDARD: Challenge using standard flow
Default to STANDARD if not provided.
User unique identifier of person/system challenges Payment Dispute.
Customer information. Applicable when Payment Dispute 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 Payment Dispute.
Deprecated. Use supporting_documents.documents.description instead.
The defense information when a Payment Dispute 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 Payment Dispute 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 Payment Dispute 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 Payment Dispute 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 Payment Dispute stage is CHARGEBACK.
Seller information. Applicable when Payment Dispute 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 Payment Dispute event.
The time when the user accepted the Payment Dispute.
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 Payment Dispute.
Indicates whether AI Dispute Automation is available. Possible values: AVAILABLE, UNAVAILABLE.
Payment Dispute 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 Payment Dispute stage is
CHARGEBACKand AI Dispute Automation status isAVAILABLE
- Applicable when Payment Dispute stage is
- STANDARD: Challenge via standard flow
Default to STANDARD if not provided.
The time when the user challenges Payment Dispute.
User unique identifier of person/system challenges Payment Dispute.
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 Payment Dispute was created.
Payment Dispute currency.
The customer unique identifier of original payment.
The customer name of original payment.
Payment Dispute due date.
Payment Dispute unique identifier.
The issuer’s comment on Payment Dispute.
The issuer’s documents on Payment Dispute.
The order unique identifier of original payment.
A set of key-value pairs attached to the dispute by the merchant.
Payment Dispute mode. Possible values: ALLOCATION, COLLABORATION, applicable when the stage is CHARGEBACK, PRE_ARBITRATION and ARBITRATION.
Payment Attempt unique identifier.
Payment Intent unique identifier.
The payment method type of original payment.
Payment Dispute reason.
Payment Dispute reason description.
Payment Dispute reason code.
Payment Dispute 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.
Payment Dispute stage. Possible values: RFI, PRE_CHARGEBACK, CHARGEBACK, PRE_ARBITRATION, ARBITRATION.
Payment Dispute status. Possible values:
- REQUIRES_RESPONSE: In this status, you can decide whether to accept or challenge the Payment Dispute.
- Applicable when receive notification from card schemes that Payment Dispute has entered
RFI,PRE_CHARGEBACK,CHARGEBACK, orPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has entered
- CHALLENGED: In this status, we have informed the issuing bank that you would like to challenge the Payment Dispute.
- Applicable when you challenge the Payment Dispute. 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 Payment Dispute or not.
- Applicable when you challenge the Payment Dispute. At
- ACCEPTED: In this status the Payment Dispute has been accepted and the payment will be refunded to the shopper.
- Applicable when you accept the Payment Dispute at
RFI,PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when you accept the Payment Dispute at
- REVERSED: In this status, the Payment Dispute has been reversed by the issuing bank. No further action is required.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
PRE_CHARGEBACK,CHARGEBACK, andPRE_ARBITRATIONstage.
- Applicable when receive notification from card schemes that Payment Dispute has been reversed at
- WON: In this status, the issuing bank has accepted the response provided, or card schemes have ruled the Payment Dispute 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 Payment Dispute 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 Payment Dispute to
PRE_ARBITRATIONstage and Airwallex is reviewing the Payment Dispute. Airwallex will decide whether to accept the Payment Dispute 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 Payment Dispute or not.
- Applicable at
PRE_ARBITRATIONandARBITRATIONstage.
- Applicable at
The transaction type of the original transaction. Possible values: PAYMENT, REFUND.
Last time at which this Payment Dispute 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.sandbox.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+00:00",36 "delivered_at": "2023-10-01T10:00:00+00:00",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+00:00",53 "reason": "Fraudulent transaction"54 }55 ],56 "due_at": "2023-11-01T10:00:00+00:00",57 "transaction_type": "PAYMENT",58 "customer_name": "John Doe",59 "created_at": "2023-10-01T10:00:00+00:00",60 "updated_at": "2023-10-01T10:00:00+00:00"61}