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.
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 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.
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 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.
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.
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:
- The fileCreate endpoint to upload files and obtain a file ID;
- The 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 |
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 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.
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 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 page.
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.
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 |
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 page).
The following examples illustrate how to achieve this via the Ryft API.
When uploading evidence to challenge a dispute (see section above), you can specify Win Dispute inside the Uncategorised evidence type to simulate winning the dispute.
{
"evidence": {
"text": {
"uncategorised": "Win Dispute"
}
}
}Once the challenge is submitted, the dispute status will be updated to Won.
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.