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 Lifecycle

The dispute process works differently across payment methods and card networks, but generally follows a similar pattern.

Early fraud warning

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:

  • TC40 reports for Visa payments
  • System to Avoid Fraud Effectively (SAFE) reports for Mastercard payments
  • Ethoca alerts

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.

Request for information

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.

Notification of 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.

Pre-Arbitration and second chargeback

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.

See below for examples of dispute statuses from popular payment service providers and how they map to Ravelin’s dispute stages.

Required Data

You can send us disputes through our API, or directly from your PSP. In either case, the data requirements are the same:

  1. Dispute Date
  2. Transaction Identifier

    In order to use disputes as labels for machine learning, Ravelin must know which specific transaction a cardholder has disputed. From this, we can identify the payment method, order, and customer responsible for the dispute. There are three identifiers we can use to find the original transaction associated with a dispute. In order of preference, these are:

    1. a transaction ID,
    2. a gateway reference, or
    3. an order ID (from which we use the first successful auth, capture, or auth_capture transaction).
  3. 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.

  4. Dispute 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:

  1. Dispute outcome (e.g. won, lost or expired)
  2. Dispute amount (defaults to the transaction amount, if missing)
  3. Dispute currency (defaults to the transaction currency, if missing)

Sharing Disputes via API

The best way to share disputes with Ravelin is through 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 the relevant Ravelin API endpoint:

Sharing Disputes via PSP Webhooks

We can also receive chargebacks directly from some payment service providers (currently Adyen and Braintree) using their webhooks. Please contact us for more information on setting this up.

Non-Fraud Chargebacks

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.

Set the nonFraud boolean field to true when sending a dispute to our API to inform us that a payment was disputed for reasons other than fraud, as we will otherwise treat the dispute as an indicator of fraudulent behaviour.

Liability Shift

You are not always liable to pay the costs of a chargeback if a third-party has taken liability for the transaction. This is most often true when a transaction has successfully passed a 3D Secure (3DS) check. In this case the issuer will become liable for the chargeback amount.

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, please inform us via our API by setting the liabilityShifted boolean field to true.

PSP Dispute Statuses

See below for how disputes data from Adyen, Braintree and Stripe map 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


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
Braintree Dispute Status Ravelin Dispute Outcome
Disputed -
Open -


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 -
needs_response CHARGEBACK -
under_review CHARGEBACK LOST