Risk-team icon

Dispute webhooks

Learn about dispute events that trigger a webhook message.

Adyen sends you a webhook message when a payment is disputed. You can use these webhook messages to alert staff of (pending) chargebacks, so that they can take appropriate action.

A dispute webhook message contains:

  • eventCode: Indicates an event type in the dispute process.
  • pspReference: The PSP reference of the dispute. All events related to a dispute have the same PSP reference.
  • originalReference: The PSP reference of the disputed payment.

Most webhook messages also contain a dispute status in the additionalData object. The disputeStatus field gives more information about the status of the dispute at the time of the event. For example, if the dispute was won, lost, has expired or is pending.

The disputeStatus is not returned in webhook messages for disputed payments processed in Brazil.

Requirements

Before you begin, take into account the following requirements and limitations.

Requirement Description
Integration type Make sure that you have built an online payments integration.
Customer Area roles To manage webhooks in the Customer Area, make sure that you have one of the following roles:
  • Merchant admin
  • Merchant technical integrator
Limitations The disputeStatus is not returned in webhook messages for disputed payments processed in Brazil.
Setup steps You can manage disputes using the Disputes API or the Customer Area. For either flow, we recommend that you:

Dispute events

The following tables show an overview of the dispute event types, what they mean, and where applicable, the possible values for the dispute status:

Webhook eventCode Description Possible disputeStatus values
NOTIFICATION_OF_FRAUD The alert passed on by issuers to schemes and subsequently to processors. Visa calls them TC40 and Mastercard calls them System to Avoid Fraud Effectively (SAFE). These are informational webhooks offered at no charge by Adyen, letting you take action, such as blocking a shopper or issuing a refund before a chargeback is incurred. Not applicable
REQUEST_FOR_INFORMATION Information requested for this payment.
  • Unresponded
  • Responded
  • Expired
NOTIFICATION_OF_CHARGEBACK Adyen has received a notification from the scheme that a chargeback is incoming on a payment. This webhook informs you of that event. This is your starting point for the defense, and marks the start of the defense period. Use the Disputes API or the Customer Area to evaluate the chargeback. You can now start your defense, you do not have to wait for the CHARGEBACK webhook.
  • Undefended
  • Pending
INFORMATION_SUPPLIED You have successfully uploaded your dispute defense documents, or Adyen has auto-defended the dispute.
  • Responded
  • Pending
CHARGEBACK A payment was charged back.
  • Undefended
  • Pending
  • Lost
  • Accepted
SECOND_CHARGEBACK The issuing bank declines the material submitted during defense of the original chargeback.
  • Lost
CHARGEBACK_REVERSED A chargeback has been defended towards the issuing bank, and the disputed amount was transferred back to your account. The dispute status will be Pending while the issuing bank reviews the material. This stage is not final and a "second" chargeback can be presented by the issuing bank, resulting in losing the chargeback case.

Only for the Visa allocation flow, the final status can be Won if the issuing bank accepts the defense in pre-arbitration.
PREARBITRATION_WON The pre-arbitration case that was initiated has been accepted by the cardholder's bank. This event code is only used for disputes that can include pre-arbitration, such as the Visa allocation flow or the UnionPay flow.
  • Won
PREARBITRATION_LOST The Pre-Arbitration case that was initiated has been declined by the cardholder's bank. This event code is only used for disputes that can include pre-arbitration, such as the Visa allocation flow or the UnionPay flow.
  • Lost
DISPUTE_DEFENSE_PERIOD_ENDED You have not defended the dispute within the timeframe, or the defense period ended because you accepted liability for the chargeback and will not defend the dispute.
  • Undefended
  • Lost
  • Accepted
ISSUER_RESPONSE_TIMEFRAME_EXPIRED The issuer either accepted your defense of the dispute, or did not respond in time.
  • Won
ISSUER_COMMENTS Includes any free-text issuer comments that include relevant information about the dispute process, such as why the issuer decided to initiate or continue the dispute. You can receive issuer comments for chargebacks and pre-arbitration cases. Not applicable

Enable webhooks

Make sure that you set up a Standard webhook, and that you select all dispute events. For details on how to configure and manage webhooks, refer to Webhooks.

A dispute webhook message can contain two PSP references:

  • pspReference: The PSP reference of the dispute. All events related to a dispute have the same PSP reference.
  • originalReference: The PSP reference of the disputed payment.

To return the PSP reference of the payment in the originalReference field, and the PSP reference of the dispute in the pspReference for the event types CHARGEBACK_REVERSED, SECOND_CHARGEBACK, PREARBITRATION_WON and PREARBITRATION_LOST, follow these steps:

  1. Log in to your Customer Area
  2. Go to Developers > Webhooks.
  3. Next to Standard webhook select the edit webhook icon .
  4. Under Additional Settings > Risk select the edit icon .
  5. Enable Include the originalReference for CHARGEBACK_REVERSED events, and then select Apply.
  6. Select Save changes.

NOTIFICATION_OF_FRAUD

For possible values for the reason and nofReasonCode  fields, refer to Dispute reason codes.

{
   "live":"true",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "modificationMerchantReferences":"",
               "nofReasonCode":"6",
               "paymentMethodVariant":"mcsuperpremiumcredit",
               "nofSchemeCode":"mc",
            },
            "amount":{
               "currency":"USD",
               "value":10089
            },
            "eventCode":"NOTIFICATION_OF_FRAUD",
            "eventDate":"2020-07-19T04:01:13+02:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "originalReference":"9913333333333333",
            "paymentMethod":"mc",
            "pspReference":"9915555555555555",
            "reason":"Card Not Present Fraud",
            "success":"true"
         }
      }
   ]
}

REQUEST_FOR_INFORMATION

For possible values for the reason and rfiReasonCode  fields, refer to Dispute reason codes.

{
   "live":"true",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
                "rfiSchemeCode":"visa",
                "modificationMerchantReferences":"",
                "rfiReasonCode":"28",
                "defensePeriodEndsAt":"2021-05-06T22:09:50+02:00",
                "disputeStatus" : "Unresponded"
            },
             "amount":{
               "currency":"USD",
               "value":1000
            },
            "eventCode":"REQUEST_FOR_INFORMATION",
            "eventDate":"2021-04-18T22:09:50+01:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "originalReference":"9913333333333333",
            "paymentMethod":"visa",
            "pspReference":"9915555555555555",
            "reason":"Request for copy bearing signature",
            "success":"true"
         }
      }
   ]
}

NOTIFICATION_OF_CHARGEBACK

For a list of all values for reason and chargebackReasonCode  fields, refer to Dispute reason codes.

{
   "live":"true",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "chargebackReasonCode":"10.4",
               "modificationMerchantReferences":"",
               "chargebackSchemeCode":"visa",
               "defensePeriodEndsAt":"2021-05-24T16:05:30+03:00",
               "autoDefended":"false",
               "defendable":"true",
               "disputeStatus":"Undefended"
            },
            "amount":{
               "currency":"EUR",
               "value":1000
            },
            "eventCode":"NOTIFICATION_OF_CHARGEBACK",
            "eventDate":"2021-05-06T16:05:30+03:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "originalReference":"9913333333333333",
            "paymentMethod":"visa",
            "pspReference":"9915555555555555",
            "reason":"Other Fraud-Card Absent Environment",
            "success":"true"
         }
      }
   ]
}

INFORMATION_SUPPLIED

For a list of all values for reason and chargebackReasonCode  fields, refer to Dispute reason codes.

{
   "live" : "true",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "chargebackReasonCode" : "13.3",
               "chargebackSchemeCode" : "visa",
               "disputeStatus" : "Pending"
            },
            "amount" : {
               "currency" : "USD",
               "value" : 10000
            },
            "eventCode" : "INFORMATION_SUPPLIED",
            "eventDate" : "2021-05-17T09:35:14+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "originalReference" : "9914444444444444",
            "merchantReference" : "YOUR_REFERENCE",
            "paymentMethod" : "visa",
            "pspReference" : "9915555555555555",
            "reason" : "Not as Described or Defective Merchandise/Services",
            "success" : "true"
         }
      }
   ]
}

CHARGEBACK

For a list of all values for reason and chargebackReasonCode  fields, refer to Dispute reason codes.

{
   "live":"true",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData":{
               "chargebackReasonCode":"10.4",
               "modificationMerchantReferences":"",
               "chargebackSchemeCode":"visa",
               "defensePeriodEndsAt":"2021-05-24T22:09:50+02:00",
               "defendable" : "true",
               "disputeStatus" : "Undefended"
            },
            "amount":{
               "currency":"EUR",
               "value":1000
            },
            "eventCode":"CHARGEBACK",
            "eventDate":"2021-05-06T22:09:50+02:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "originalReference":"9913333333333333",
            "paymentMethod":"visa",
            "pspReference":"9915555555555555",
            "reason":"Other Fraud-Card Absent Environment",
            "success":"true"
         }
      }
   ]
} 

SECOND_CHARGEBACK

For a list of all values for reason and chargebackReasonCode  fields, refer to Dispute reason codes.

To return the originalReference in the SECOND_CHARGEBACK webhook:

  1. Log in to your Customer Area
  2. Go to Developers > Webhooks.
  3. Next to Standard webhook select the edit webhook icon .
  4. Under Additional Settings > Risk select the edit icon .
  5. Enable Include the originalReference for CHARGEBACK_REVERSED events, and then select Apply.
  6. Select Save changes. 
    {
"live" : "true",
"notificationItems" : [
  {
     "NotificationRequestItem" : {
        "additionalData" : {
           "chargebackReasonCode" : "13.1",
           "modificationMerchantReferences" : "",
           "chargebackSchemeCode" : "visa",
           "disputeStatus" : "Lost"
        },
        "amount" : {
           "currency" : "GBP",
           "value" : 10000
        },
        "eventCode" : "SECOND_CHARGEBACK",
        "eventDate" : "2020-03-13T11:35:42+01:00",
        "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
        "merchantReference" : "YOUR_REFERENCE",
        "originalReference":"9913333333333333",
        "paymentMethod" : "visa",
        "pspReference" : "9915555555555555",
        "reason" : "Merchandise/Services Not Received",
        "success" : "true"
     }
  }
]
}

CHARGEBACK_REVERSED

To return the originalReference in the CHARGEBACK_REVERSED webhook:

  1. Log in to your Customer Area
  2. Go to Developers > Webhooks.
  3. Next to Standard webhook select the edit webhook icon .
  4. Under Additional Settings > Risk select the edit icon .
  5. Enable Include the originalReference for CHARGEBACK_REVERSED events, and then select Apply.
  6. Select Save changes.
{
   "live":"true",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData" : {
                "disputeStatus" : "Pending"
            },
            "amount":{
               "currency":"EUR",
               "value":1000
            },
            "eventCode":"CHARGEBACK_REVERSED",
            "eventDate":"2020-03-23T13:55:31+01:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "originalReference":"9913333333333333",
            "paymentMethod":"mc",
            "pspReference":"9915555555555555",
            "reason":"No Cardholder Authorization",
            "success":"true"
         }
      }
   ]
}

PREARBITRATION_WON

To return the originalReference in the PREARBITRATION_WON webhook:

  1. Log in to your Customer Area
  2. Go to Developers > Webhooks.
  3. Next to Standard webhook select the edit webhook icon .
  4. Under Additional Settings > Risk select the edit icon .
  5. Enable Include the originalReference for CHARGEBACK_REVERSED events, and then select Apply.
  6. Select Save changes.
{
   "live":"true",
   "notificationItems":[
      {
         "NotificationRequestItem":{
            "additionalData" : {
               "disputeStatus" : "Won"
            },
            "amount":{
               "currency":"EUR",
               "value":1000
            },
            "eventCode":"PREARBITRATION_WON",
            "eventDate":"2020-03-23T13:55:31+01:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "originalReference":"9913333333333333",
            "paymentMethod":"visa",
            "pspReference":"9915555555555555",
            "reason":"Other Fraud-Card Absent Environment",
            "success":"true"
         }
      }
   ]
}

PREARBITRATION_LOST

To return the originalReference in the PREARBITRATION_LOST webhook:

  1. Log in to your Customer Area
  2. Go to Developers > Webhooks.
  3. Next to Standard webhook select the edit webhook icon .
  4. Under Additional Settings > Risk select the edit icon .
  5. Enable Include the originalReference for CHARGEBACK_REVERSED events, and then select Apply.
  6. Select Save changes. 
    {
"live":"true",
"notificationItems":[
  {
     "NotificationRequestItem":{
        "additionalData" : {
          "disputeStatus" : "Lost"
        },
        "amount":{
           "currency":"EUR",
           "value":1000
        },
        "eventCode":"PREARBITRATION_LOST",
        "eventDate":"2020-03-23T13:55:31+01:00",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "merchantReference":"YOUR_REFERENCE",
        "originalReference":"9913333333333333",
        "paymentMethod":"visa",
        "pspReference":"9915555555555555",
        "reason":"Other Fraud-Card Absent Environment",
        "success":"true"
     }
  }
]
}

DISPUTE_DEFENSE_PERIOD_ENDED

See Dispute timeframes for an overview of the defense periods for different schemes.

{
   "live":"true",
   "notificationItems":[
      {
         "NotificationRequestItem":{
           "additionalData":{
               "chargebackReasonCode":"10.4",
               "modificationMerchantReferences":"",
               "chargebackSchemeCode":"visa",
               "disputeStatus" : "Lost"
            },
            "amount":{
               "currency":"EUR",
               "value":1000
            },
            "eventCode":"DISPUTE_DEFENSE_PERIOD_ENDED",
            "eventDate":"2020-11-11T01:30:57+01:00",
            "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
            "merchantReference":"YOUR_REFERENCE",
            "originalReference":"9914444444444444",
            "paymentMethod":"visa",
            "pspReference":"9915555555555555",
            "reason":"Other Fraud-Card Absent Environment",
            "success":"true"
         }
      }
   ]
}

ISSUER_RESPONSE_TIMEFRAME_EXPIRED

{
   "live" : "true",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
               "chargebackReasonCode" : "13.1",
               "chargebackSchemeCode" : "visa",
               "modificationMerchantReferences" : "",
               "disputeStatus" : "Won"
            },
            "amount" : {
               "currency" : "USD",
               "value" : 10000
            },
            "eventCode" : "ISSUER_RESPONSE_TIMEFRAME_EXPIRED",
            "eventDate" : "2021-05-19T09:35:14+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "originalReference" : "9914444444444444",
            "merchantReference" : "YOUR_REFERENCE",
            "paymentMethod" : "visa",
            "pspReference" : "9915555555555555",
            "reason" : "Merchandise/Services Not Received",
            "success" : "true"
         }
      }
   ]
}

ISSUER_COMMENTS

For examples of which issuer comments you can receive, see issuer comments.

{
   "live" : "true",
   "notificationItems" : [
      {
         "NotificationRequestItem" : {
            "additionalData" : {
                "chargebackReasonCode" : "13.3",
                "chargebackSchemeCode" : "visa",
                "issuerComments.type": "chargeback",
                "issuerComments.disputeAmountChangeReason": "some_text",
                "issuerComments.cancellationMethod": "some_text",
                "issuerComments.orderDetailsNotAsDescribed": "some_text",
                "issuerComments.explanation": "some_text",
                "issuerComments.damagedOrDefectiveOrderInfo": "some_text",
                "issuerComments.howChAttemptReturnAndDispOfMerchandise": "some_text",
                "issuerComments.whatWasNotReceived": "some_text",
                "issuerComments.cancellationDate": "some_text"
            },
            "amount" : {
               "currency" : "EUR",
               "value" : 1000
            },
            "eventCode" : "ISSUER_COMMENTS",
            "eventDate" : "2021-05-17T09:35:14+02:00",
            "merchantAccountCode" : "YOUR_MERCHANT_ACCOUNT",
            "originalReference" : "9914444444444444",
            "merchantReference" : "YOUR_REFERENCE",
            "paymentMethod" : "visa",
            "pspReference" : "9915555555555555",
            "reason" : "Not as Described or Defective Merchandise/Services",
            "success" : "true"
         }
      }
   ]
}

See also