Disputes (including chargebacks) are essential to fraud prevention. A disputed payment informs us that the customer was likely not the real cardholder, allowing us to report fraud rates and improve our automated fraud prevention to better differentiate between genuine and fraudulent behaviour in the future.
The dispute process works differently across payment methods and card networks, but generally follows a similar pattern.
Each of the stages of the dispute lifecycle are explained below:
The first indicator of a disputed card payment is often an early fraud warning (also known as a notification of fraud). Examples of early fraud warnings include:
At this stage the dispute is not yet a chargeback and no money has been withdrawn from your merchant account.
When you receive an early fraud warning we recommend refunding the transaction and stopping the order (if still possible). Depending on your configuration, Ravelin will automatically prevent future orders from a customer once you notify us of a dispute (including early fraud warnings) associated with one of their transactions.
Depending on the issuer of the payment method, you may also receive a request for information before a chargeback. This process is also known as a ‘retrieval’ or ‘inquiry’. At this stage, you also have an opportunity to refund the transaction or provide the evidence requested to avoid the dispute becoming a chargeback.
When the issuer sends a notification of chargeback you have an opportunity to provide evidence to defend the disputed payment. Your payment service provider (PSP) may automatically defend some chargebacks for you, for example, if liability shift occurred on the original transaction.
When you receive the first chargeback, the disputed amount is withdrawn from your merchant account. A dispute will not progress beyond this stage if you accept it or do not provide evidence to defend the dispute within the required timeframe.
The issuer may escalate a dispute to pre-arbitration. This may happen if you successfully defended and won the first chargeback dispute, but the cardholder provided new evidence to back up their dispute. At this stage, you can either accept the dispute, which leads to a second chargeback, or challenge the dispute again, which leads to arbitration.
Arbitration is the final stage a dispute can reach. At this stage, the issuer and the merchant agree to request a ruling from the card network. An arbitration case is likely to involve significant additional cost and may only be worthwhile for an exceptionally high value dispute.
Send via our API
If your PSP provides you API or webhook access to your disputes, you can
use the data they provide to send disputes to our Dispute Endpoint.
Upload via the Ravelin dashboard
You can manually upload a CSV file of disputes using the Dispute Uploader in the Ravelin dashboard.
This can be accessed from the Tools section of the dashboard. Ensure you use the Dispute
Upload Template which is available on the Dispute Uploader page.
Send via PSP Webhooks
We can also receive disputes directly from
Adyen,
Braintree and
Stripe using webhooks.
Please contact us for more information on setting this up.
Transaction ID,
Gateway Reference or
Order ID
In order to use disputes as labels for machine learning, we need to be able to associate
disputes with the original transactions.
Most payment gateways will provide an identifier for the original transaction with every dispute.
There are three identifiers we can use to associate a dispute with the original transaction:
If the transaction identifier is provided by the merchant, use transactionId.
If the transaction identifier is generated by the payment gateway, use the gatewayReference field.
If only the original orderId is known, we will guess that the first successful auth, capture,
or auth_capture transaction associated with the order is being disputed.
If we do not find a transaction with a matching transactionId, gatewayReference or orderId we will ignore the dispute.
Dispute ID
Allows us to keep track of the dispute. If you do not store your
disputes in a system that provides a dispute ID, you can use the
transaction ID, gateway reference, or order ID in its place but be aware of
the potential for collisions.
Stage
In order to accurately report fraud rates and chargeback rates, Ravelin must
be able to determine which disputes have progressed to a chargeback (or
equivalent stage for non-card payments), and which are earlier-stage disputes
such as early fraud warnings (also known as notifications of fraud) or requests
for information.
It is also useful to send us the following for reporting purposes:
Outcome
Either ACCEPTED, WON, LOST or EXPIRED.
Amount
Defaults to the transaction amount, if missing.
Currency
Defaults to the transaction currency, if missing.
Cardholders can also dispute payments for reasons other than fraud. For example, it is often possible to dispute a credit card payment if goods arrive damaged or are not as described.
To inform us that a payment was disputed for reasons other than fraud set the
dispute.nonFraud field to true,
otherwise we will treat the dispute as an indicator of fraudulent behaviour.
You are not always liable to pay the costs of a chargeback if the issuer has taken liability for the transaction. This is most often true when a transaction has successfully passed a 3D Secure (3DS) check.
Ravelin will automatically flag chargebacks as being subject to a liability shift if we have received record that the associated transaction successfully passed 3DS.
If there are other scenarios for which liability of a chargeback has been shifted from you, set the
dispute.liabilityShifted field to true.
See below for how dispute data from Adyen, Braintree, Stripe and PayPal maps to Ravelin’s dispute stages and outcomes.
Adyen’s Dispute notifications
provide an eventCode that can describe both the lifecycle stage and outcome of a dispute.
| Adyen Event Code | Ravelin Dispute Stage | Ravelin Dispute Outcome |
|---|---|---|
NOTIFICATION_OF_FRAUD |
EARLY_FRAUD_WARNING |
- |
REQUEST_FOR_INFORMATION |
REQUEST_FOR_INFORMATION |
- |
NOTIFICATION_OF_CHARGEBACK |
NOTIFICATION_OF_CHARGEBACK |
- |
CHARGEBACK |
CHARGEBACK |
LOST |
SECOND_CHARGEBACK |
SECOND_CHARGEBACK |
LOST |
CHARGEBACK_REVERSED |
CHARGEBACK |
WON |
PREARBITRATION_WON |
PREARBITRATION |
WON |
PREARBITRATION_LOST |
PREARBITRATION |
LOST |
Braintree describe the lifecycle stage of a dispute using their kind field, and the outcome
of the dispute using their status field in the
Braintree API.
Here’s how each map to Ravelin’s equivalents:
| Braintree Dispute Kind | Ravelin Dispute Stage |
|---|---|
Retrieval |
REQUEST_FOR_INFORMATION |
Chargeback |
CHARGEBACK |
PreArbitration |
PREARBITRATION |
| Braintree Dispute Status | Ravelin Dispute Outcome |
|---|---|
Accepted |
ACCEPTED |
Disputed |
- |
Expired |
EXPIRED |
Open |
- |
Lost |
LOST |
Won |
WON |
Stripe’s Early Fraud Warning notifications are separate from their Disputes. Ensure you send both to Ravelin.
| Stripe Object | Ravelin Dispute Stage | Ravelin Dispute Outcome |
|---|---|---|
early_fraud_warning |
EARLY_FRAUD_WARNING |
- |
| Stripe Dispute Status | Ravelin Dispute Stage | Ravelin Dispute Outcome |
|---|---|---|
warning_needs_response |
REQUEST_FOR_INFORMATION |
- |
warning_under_review |
REQUEST_FOR_INFORMATION |
- |
warning_closed |
REQUEST_FOR_INFORMATION |
WON |
needs_response |
NOTIFICATION_OF_CHARGEBACK |
- |
under_review |
NOTIFICATION_OF_CHARGEBACK |
- |
charge_refunded |
- | - |
won |
CHARGEBACK |
WON |
lost |
CHARGEBACK |
LOST |
PayPal’s Disputes API
provides a dispute lifecycle stage
and outcome code
that map to Ravelin’s dispute stage and outcome.
| PayPal Dispute Lifecycle Stage | Ravelin Dispute Stage |
|---|---|
INQUIRY |
REQUEST_FOR_INFORMATION |
CHARGEBACK |
CHARGEBACK |
PRE_ARBITRATION |
PREARBITRATION |
ARBITRATION |
ARBITRATION |
| PayPal Dispute Outcome Code | Ravelin Dispute Outcome |
|---|---|
RESOLVED_BUYER_FAVOUR |
LOST |
RESOLVED_SELLER_FAVOUR |
WON |
RESOLVED_WITH_PAYOUT |
WON |
CANCELED_BY_BUYER |
WON |
NONE |
- |
Perform manual reviews to help us identify fraudsters
Test your payment fraud integration
Was this page helpful?