Payment Fraud Integration

Sending Disputes

On this page:

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.

Each of the stages of the dispute lifecycle are explained below:

1. 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.

2. 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.

3. 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.

4. Chargeback

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.

5. 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.

6. 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.

Sending disputes

  • 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.

Required data

  • Dispute Time

  • 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.

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.

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.

Liability shift

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.

PSP Dispute Statuses

See below for how dispute data from Adyen, Braintree, Stripe and PayPal maps to Ravelin’s dispute stages and outcomes.

Adyen

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

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

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

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 -

Next steps

Perform manual reviews to help us identify fraudsters

Test your payment fraud integration

Feedback