# Manage Disputes

## Overview

[**Disputes**](/documentation/overview/core_concepts/disputes), also known as chargebacks, occur when a customer questions a transaction on their account statement and requests their bank or card issuer to reverse the payment. This can happen for various reasons, such as unauthorized transactions, dissatisfaction with the product or service, or billing errors.

When a dispute is initiated, the funds associated with the transaction are typically held by the bank or card issuer while they investigate the claim:

- If the dispute is resolved in **favor of the customer**, the funds are returned to them, and the merchant may incur additional fees.
- If the dispute is resolved in **favor of the merchant**, the funds are released back to the merchant's account.


Ryft provides the Dispute API and the Ryft Portal to help Main Account holders manage and respond to disputes effectively. They allow you to retrieve information about disputes, accept or challenge disputes, upload evidence, and track the status of disputes.

## Prerequisites

To manage disputes, you need to have a payment that has been processed through Ryft and is currently under dispute.

You can retrieve a list of disputes along with their details using the [disputesList](/documentation/api/reference/openapi#operation/disputesList) endpoint or by navigating to the Disputes section in the Ryft Portal.

Please note we always recommend explicitly responding to disputes, either by accepting or challenging them. If no action is taken before the dispute response deadline, the dispute will be automatically considered **lost**, and the funds will be returned to the customer.

## Accepting a Dispute

If you choose to **accept** a dispute, you acknowledge the customer's claim, and the funds associated with the transaction will be returned to the customer.

You can accept a dispute using the [disputeAcceptById](/documentation/api/reference/openapi#operation/disputeAcceptById) endpoint or by selecting the dispute in the Ryft Portal and clicking the "Accept Dispute" button.

Once a dispute is accepted, its status will be updated to **Accepted**, and the funds will be returned to the customer. Please note that accepting a dispute may incur additional fees.

## Challenging a Dispute

If you believe that the dispute is invalid or that you have sufficient evidence to prove that the transaction was legitimate, you can choose to **challenge** the dispute.

When challenging a dispute, you will need to provide evidence to support your claim. This evidence can include transaction details, customer communication, proof of delivery, or any other relevant information.

Ryft provides a strong evidence management system to help you gather and submit the necessary evidence to challenge a dispute effectively. You should make use of the **Recommended Evidence** section provided in the Ryft Portal or via the API for each dispute, which outlines the specific types of evidence that are most relevant to the dispute reason code.

### Uploading Evidence

You can upload evidence to support your dispute challenge using either the Ryft API or the Ryft Portal.

You can upload evidence using the **API** via two steps:

1. The [fileCreate](/documentation/api/reference/openapi#operation/fileCreate) endpoint to upload files and obtain a file ID;
2. The [disputeUploadEvidence](/documentation/api/reference/openapi#operation/disputeUploadEvidence) endpoint to attach the uploaded files to the dispute.


Alternatively, you can upload evidence directly in the **Ryft Portal** by selecting the dispute, navigating to the **Evidence** section, and uploading the relevant files.

Ryft supports the following types of evidence:

| Evidence | Description | Type |
|  --- | --- | --- |
| ProofOfDelivery | Your proof of delivery or service (e.g. document from the courier) | File |
| BillingAddress | The billing address for the transaction | Text |
| ShippingAddress | The address you shipped the goods/service to | Text |
| DuplicateTransaction | Any comments/explanation you may have to counter the claim that the transaction was a duplicate | Text |
| CustomerSignature | Your proof that the customer signed for the goods | File |
| Receipt | The invoice or receipt for the payment | File |
| ShippingConfirmation | Document showing the order was shipped (make sure this also shows the shipping address) | File |
| CustomerCommunication | Any communication with the customer (email, text etc.) that show the payment was legitimate | File |
| RefundPolicy | Your refund policy which demonstrates why the customer is not eligible for a refund in this case | File |
| CancellationPolicy | Your cancellation policy which demonstrates why the customer is not eligible for a refund in this case | File |
| RecurringPaymentAgreement | Your recurring payment agreement | File |
| Uncategorised | Fraud | File & Text |


### Submitting the Challenge

Once you have gathered and uploaded the necessary evidence, you can proceed to **challenge** the dispute, either through the Ryft API or the Ryft Portal.

You can challenge a dispute using the [disputeChallengeById](/documentation/api/reference/openapi#operation/disputeChallengeById) endpoint.

Alternatively, in the **Ryft Portal**, select the dispute, navigate to the **Evidence** section, and click the *Challenge Dispute* button.

Please note that you should submit the challenge only once you have uploaded all the relevant evidence. Once a dispute challenge is submitted, it cannot be modified, and no additional evidence can be added.

After submitting the challenge, the dispute status will be updated to "Challenged," and the evidence will be sent to the customer's bank or card issuer for review.

The timeframe for resolving a challenged dispute may vary depending on the payment method and the policies of the acquiring bank.

### Tracking Dispute Status

Once a dispute has been challenged, you can **track** its status using one or more of the following methods:

- **Ryft Portal**: Navigate to the Disputes section in the Ryft Portal to view the status of all disputes, including those that have been challenged.
- **Ryft API**: Use the [disputesList](/documentation/api/reference/openapi#operation/disputesList) endpoint to retrieve a list of disputes and check their statuses.
- **Webhooks**: Set up webhooks to receive real-time notifications about dispute status changes. You can find more information about setting up webhooks in the [Webhooks](/documentation/get_started/webhooks) page.


## Testing Disputes

We support testing disputes in our Sandbox environment. This allows you to simulate dispute scenarios and test your dispute management processes without affecting real transactions.

You can:

- Create test payments that trigger a corresponding dispute;
- Upload specific evidence to simulate the dispute being won or lost.


### Creating Test Disputes

To create a test dispute in the Sandbox environment, you can create a Payment Session with the exact amount specified in the table below. This will trigger a dispute with the corresponding reason code.

| Amount | Description |
|  --- | --- |
| `4531` | Creates a dispute with category **Fraud** |
| `1233` | Creates a dispute with category **Authorization** |
| `855` | Creates a dispute with category **Processing** |
| `6767` | Creates a dispute with category **Cardholder** |


### Resolving Test Disputes

Based on the evidence you upload when challenging a test dispute, the outcome can be simulated as either won or lost. This action can be performed both via the Ryft API and the Ryft Portal ([Disputes](/documentation/get_started/portal/disputes) page).

The following examples illustrate how to achieve this via the Ryft API.

Winning a Test Dispute
When uploading evidence to challenge a dispute (see [section](#challenging-a-dispute) above), you can specify `Win Dispute` inside the `Uncategorised` evidence type to simulate winning the dispute.


```json Win Dispute Evidence Example
{
    "evidence": {
        "text": {
            "uncategorised": "Win Dispute"
        }
    }
}
```

Once the challenge is [submitted](#submitting-the-challenge), the dispute status will be updated to **Won**.

Losing a Test Dispute
When uploading evidence to challenge a dispute (see [section](#challenging-a-dispute) above), you can specify `Lose Dispute` inside the `Uncategorised` evidence type to simulate losing the dispute.


```json Lose Dispute Evidence Example
{
    "evidence": {
        "text": {
            "uncategorised": "Lose Dispute"
        }
    }
}
```

Once the challenge is [submitted](#submitting-the-challenge), the dispute status will be updated to **Lost**.

## Considerations

When managing disputes, please keep the following considerations in mind:

- The timeframe for resolving disputes may vary depending on the payment method and the policies of the acquiring bank.
- Providing strong and relevant evidence is crucial when challenging a dispute, as it increases the likelihood of a successful outcome.
- Maintain clear and organized records of transactions, customer communications, and evidence to facilitate effective dispute management.
- Consider implementing fraud prevention measures to reduce the likelihood of disputes arising from unauthorized transactions.
- Educate your customer service team on handling disputes and communicating effectively with customers to resolve issues before they escalate to formal disputes.