Documentation Index
Fetch the complete documentation index at: https://docs.xpaycheckout.com/llms.txt
Use this file to discover all available pages before exploring further.
What are Disputes?
A dispute is initiated when a customer challenges a transaction through their issuing bank. The bank investigates the claim and may reverse the payment (a chargeback) unless the merchant provides strong evidence. Disputes can occur when a customer questions a charge on their card. This page explains how disputes work, where to track them, how to respond, and the implications of missing deadlines.Dispute reason codes
Each dispute may include a machine-readable reason code that reflects why the customer or bank challenged the charge. When you see a code on a dispute in the dashboard, use the descriptions below to understand the claim and what evidence to gather.Card and chargeback reasons
| Code | Description |
|---|---|
credit_not_processed | The cardholder claims you have not yet refunded their return or cancellation. |
duplicate | The customer was charged more than once for the same item or service. |
fraudulent | The customer claims they didn’t authorize this payment — possibly due to card fraud or confusion over a legitimate charge. |
general | The customer disputed the charge, but the reason is unclear. You should contact them for more details. |
product_not_received | The customer says they didn’t receive the product or service they paid for. |
product_unacceptable | The customer received the product but says it was damaged, defective, or not as described. |
subscription_canceled | The customer says you continued charging them after they canceled a subscription. |
unrecognized | The customer doesn’t recognize the charge on their statement. This often overlaps with fraudulent disputes. |
customer_initiated | The customer initiated a chargeback directly with their bank for an unspecified reason. |
Bank, ACH, and check reasons
| Code | Description |
|---|---|
debit_not_authorized | The debit was not authorized by the account holder, often indicating possible fraud or misunderstanding. |
incorrect_account_details | The transaction failed due to incorrect or invalid account information provided. |
bank_cannot_process | The bank was unable to process the transaction due to a temporary or permanent issue. |
check_returned | The check payment was returned, possibly due to insufficient funds or a closed account. |
insufficient_funds | The customer’s account did not have enough funds to cover the transaction. |
How Disputes Occur
- Customer raises a complaint with their bank.
- The bank initiates a chargeback request.
- xPay marks the transaction as DISPUTED.
- Funds are held until resolution.
- Merchant is notified to respond with evidence.
A timely and thorough response increases the chances of reversing the chargeback.
Where to See Disputes & Notifications
Disputes can be accessed from the xPay Dashboard:- Path:
Dashboard → Disputes - View disputes with statuses:
DISPUTEDDISPUTE_UNDER_REVIEW
- Notification channels:
- Email notifications
Dispute Status Lifecycle
Status Definitions:| Status | Description |
|---|---|
DISPUTED | A dispute has been raised and is awaiting merchant action. |
DISPUTE_UNDER_REVIEW | Evidence submitted; the bank is reviewing the case. |
DISPUTE_WON | The bank ruled in your favor — funds are returned. |
DISPUTE_LOST | The bank ruled against you — funds are permanently deducted. |
All status changes are visible in real-time in the dashboard.
Evidence Guidelines
Submit clear and relevant proof to support your case.
- Upload clear, legible documents that support your case
- Mandatory evidence documents: Customer communication and payment invoice
- Include any other relevant evidence based on the dispute reason, such as your refund policy, service records, or activity logs
- Ensure all the evidence is properly labeled
- Navigate to
Dashboard → Disputes → Open Dispute -> Counter Dispute
- Navigate to
Dashboard → Disputes → Open Dispute -> Accept Dispute
Deadline and Consequences
- Deadline to submit evidence varies per dispute. Please refer to the dashboard for the specific deadline mentioned on each dispute case.
- Dispute is automatically lost.
- Disputes affect your merchant performance score.
Dispute Fees
- When a dispute is raised, the transaction amount is temporarily withdrawn.
- If you win, the amount is credited back to your account.
- If you lose or do not respond, the deduction is finalized and a fee may apply.