Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Risk-management icon

Dispute notifications

Learn about dispute events that trigger a notification.

Adyen notifies you of any disputed payments. You can use these notifications to alert staff of (pending) chargebacks, so that they can take appropriate action.

A dispute webhook notification contains:

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

Most webhooks also contain a dispute status in the additionalData object:

  • disputeStatus: This field gives more information about the stage the dispute is in.

For more information on the dispute flow and process, refer to Understanding and defending disputes

The following tables show an overview of the webhook event codes, 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 notifications 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 don't have to wait for the CHARGEBACK webhook.
  • Undefended
  • Pending
CHARGEBACK A payment was charged back.
  • Undefended
  • Pending
  • Lost
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. This stage is not final and a "second" chargeback can be presented by the issuing bank, resulting in losing the chargeback case.
  • Pending
  • Won
PREARBITRATION_WON Pre-Arbitration that you initiated has been accepted by the cardholder's bank.
  • Pending
  • Won
PREARBITRATION_LOST Pre-Arbitration that you initiated has been declined by the cardholder's bank.
  • Lost

For some webhooks, more configuration is needed on our end. Contact our Support Team to enable the following webhooks:

Webhook eventCode Description Possible disputeStatus values
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
INFORMATION_SUPPLIED You have successfully uploaded your dispute defense documents, or Adyen has auto-defended the dispute.
  • Responded
  • Pending
ISSUER_RESPONSE_TIMEFRAME_EXPIRED The issuer either accepted your defense of the dispute, or did not respond in time.
  • Pending
  • Won
  • Lost
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 in the chargeback stage, and the pre-arbitration stage. Not applicable

Enable webhooks

For details on how you can receive webhooks, refer to Notification webhooks.

To return the PSP reference of the payment in the originalReference field, and the PSP reference of the dispute in the pspReference for the webhooks 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 notification select the edit webhook icon .
  4. Under Additional Settings, enable Include the originalReference for CHARGEBACK_REVERSED notifications.

NOTIFICATION_OF_FRAUD

{
   "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 notification field, refer to the documentation on the applicable scheme in Chargeback guidelines.

{
   "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 notification 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"
         }
      }
   ]
}

CHARGEBACK

For a list of all values for reason and chargebackReasonCode notification 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 notification fields, refer to Dispute reason codes.

To return the originalReference in the SECOND_CHARGEBACK notification:

  1. Log in to your Customer Area
  2. Go to Developers > Webhooks.
  3. Next to Standard notification select the edit webhook icon .
  4. Under Additional Settings, enable Include the originalReference for CHARGEBACK_REVERSED notifications.
{
   "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 notification:

  1. Log in to your Customer Area
  2. Go to Developers > Webhooks.
  3. Next to Standard notification select the edit webhook icon .
  4. Under Additional Settings, enable Include the originalReference for CHARGEBACK_REVERSED notifications.
{
   "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 notification:

  1. Log in to your Customer Area
  2. Go to Developers > Webhooks.
  3. Next to Standard notification select the edit webhook icon .
  4. Under Additional Settings, enable Include the originalReference for CHARGEBACK_REVERSED notifications.
{
   "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 notification:

  1. Log in to your Customer Area
  2. Go to Developers > Webhooks.
  3. Next to Standard notification select the edit webhook icon .
  4. Under Additional Settings, enable Include the originalReference for CHARGEBACK_REVERSED notifications.
{
   "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

To receive this webhook, more configuration is needed on our end. Contact our Support Team to enable this webhook.

{
   "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"
         }
      }
   ]
}

INFORMATION_SUPPLIED

To receive this webhook, more configuration is needed on our end. Contact our Support Team to enable this webhook.

{
   "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"
         }
      }
   ]
}

ISSUER_RESPONSE_TIMEFRAME_EXPIRED

To receive this webhook, more configuration is needed on our end. Contact our Support Team to enable this webhook.

{
   "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

To receive this webhook, more configuration is needed on our end. Contact our Support Team to enable this webhook. 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