Dispute API Manual

During an order lifecycle, a shopper may dispute a payment.
They may contact you directly to try and reach a mutually satisfactory solution, for example a (partial) refund of their payment.
Alternatively, they may raise a dispute directly with their issuer/bank. In this case, Adyen is your contact reference to handle the dispute.

The appropriate way to handle a dispute varies, based on the payment method the shopper used to confirm their order: in general, it is possible to reverse direct debit and card payments, whereas regular bank transfers or iDEAL payments cannot usually be reversed.

Depending on the type and stage of the dispute, you may or may not be able to defend it.

Adyen takes care of some cases on its own when merchant is not liable for a chargeback, some examples are:

  • The transaction was made through a secure 3d authentication
  • Bank transfers

Dispute process flow

 This diagram describes a dispute process flow.

  • A dispute can start when a transaction payment status is set to either Settled or Refunded.
  • A dispute may start with either a Request for Information (RFI) or a Notification of Chargeback (NoC).

Request for Information (RFI)

The issuer requests more information about the transaction.
This dispute status has no financial consequences; therefore, no money is withdrawn from the merchant's account.
However, if the merchant does not respond to the RFI in a timely manner, an actual chargeback may take place, this time with financial consequences.

We recommend the merchants to always respond to an RFI. If you ignore an RFI, you have fewer options to defend the dispute and a possible chargeback.
In general, a transaction receipt or an invoice are valid documents to satisfy the RFI.

Notification of Chargeback (NoC)

A Notification of Chargeback (NoC) may follow a Request for Information (RFI), or occur immediately after the transaction payment status is set to Settled or Refunded skipping the RFI step.
In most cases, a chargeback is the next step after a NoC. It usually occurs a couple of days after the NoC, and has a financial impact.

Many acquirers choose not to charge back the transaction immediately after the NoC; instead, they wait a couple of days for the merchant defense.
If the merchant uploads their defense material successfully, and the defense documents are accepted, they are still in time to reverse the chargeback.

Chargeback reversed

If the merchant defense proves to be successful, the chargeback is reversed.
This is also called a re-presentment, or  a second presentment.

Arbitration

Most acquirers do not involve merchants in the steps that follow a chargeback reversal. However, it may be useful to understand this part of the process.

MasterCard:

  • The issuer can dispute the chargeback again by issuing a second chargeback.
  • The acquirer may defend this chargeback by starting an arbitration case.

This is a costly procedure, and therefore not the default option.
A merchant can use this approach only in cooperation with the acquirer, where the acquirer makes the final decision to start an arbitration case.

VISA:

  • The issuer can start an arbitration case.
    If the information the merchant supplies to defend the chargeback is not strong enough, the issuer can immediately start an arbitration case.

Defense flow:

Submitting dispute defense material is implemented as a SOAP service. With most other API calls, the dispute service requires HTTP basic authentication. To successfully complete a dispute defense three different API calls are required: 

  1. Retrieve applicable defense reasons. For each dispute reason, there are multiple defense reasons supported by the schemes. The dispute service filters out only the relevant, applicable defense reasons for the specific payment and return them together with an overview of the defense documents required to defend the dispute.
  2. Supply/delete defense documents. In the next call, the merchant can supply all the documentation that is required for defense. It is also possible to delete documents that are no longer valid before the defense of dispute starts.
  3. Defend dispute. With the last call, the merchant can confirm the dispute defense by selecting a defense reason with sufficiently supplied documentation to support the defense. After this call, the dispute service sends the defense material to the schemes.

Audience

This manual targets developers who integrate merchants' systems with the Adyen payment platform.

Feedback

We strive to provide you with clear, concise, and complete documentation. We are committed to improving it continuously to make it accessible and easy to understand.

We appreciate your comments, and we'd love to hear your voice: drop us a line and share your thoughts with us!

  Adyen Support Team


Dispute API last update

Version Date Changes
4.3 2017 - 16 - 01 Added Test applicable dispute reasons

Version

Date

Changes

4.3 2017 - 16 - 01 Added Test applicable dispute reasons
4.2 2016 - 14 - 09 API version updated to 18.
4.1.1 2016-05-19

Modifying field description of a delete dispute defense document request field to reflect the correct usage.

4.1 2015-10-19

Added page explaining TEST and LIVE endpoints.

4.0 2015-06-23
  • Documentation migration from PDF to web-based online deliverable as main distributable asset.
  • Versioning: version reset and adoption of semantic versioning as per v. 4.0.0.
  • Manual redesign to improve readability, navigation, content findability.

2.1

2015-03-10

Modifying reference to correct external manual

2.0

2014-11-12

  • Adding delete API call

  • Using new document layout

1.0

2012-09-27

Initial version

Dispute API endpoints

This is an overview of the test and live URLs to communicate with the Dispute API using SOAP.

This is an overview of the test URL endpoints to communicate with our Dispute API using the SOAP messaging protocol. Use them to test your implementation and run QA checks.

SOAP

Dispute service

https://ca-test.adyen.com/ca/services/DisputeService

Payment service WSDL

https://ca-test.adyen.com/ca/services/DisputeService/v25?wsdl

 

This is an overview of the live URL endpoints to communicate with our Dispute API using the SOAP messaging protocol. Use them in your live/production environment.

SOAP

Dispute service

https://ca-live.adyen.com/ca/services/DisputeService

Payment service WSDL

https://ca-live.adyen.com/ca/services/DisputeService/v25?wsdl

 

Dispute notifications

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

Dispute event codes

A dispute notification contains one of the following event codes:

  • REQUEST_FOR_INFORMATION. Information requested for this payment.
  • NOTIFICATION_OF_CHARGEBACK. Chargeback is pending, but can still be defended.
  • ADVICE_OF_DEBIT. Not currently used.
  • CHARGEBACK. A payment was charged back. 
  • CHARGEBACK_REVERSED. A chargeback has been reversed (canceled).

Examples

Soap examples:

<?xml version="1.0" encoding="UTF-8"?> 
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
  <soap:Body> 
    <ns1:sendNotification xmlns:ns1="http://notification.services.adyen.com"> 
      <ns1:notification> 
        <live xmlns="http://notification.services.adyen.com">true</live> 
        <notificationItems xmlns="http://notification.services.adyen.com"> 
          <notificationRequestItem> 
           <additionalData xsi:nil="true"/> 
            <amount> 
              <currency xmlns="http://common.services.adyen.com">EUR</currency> 
              <value xmlns="http://common.services.adyen.com">65880</value> 
            </amount> 
            <eventCode>REQUEST_FOR_INFORMATION</eventCode> 
            <eventDate>2014-11-25T21:03:34.916+01:00</eventDate> 
            <merchantAccountCode>TestMerchant</merchantAccountCode> 
            <merchantReference>KK62RKCZ:hu30dz9g:001</merchantReference> 
            <operations xsi:nil="true"/> 
            <originalReference>4414137878226334</originalReference> 
            <paymentMethod>mc</paymentMethod> 
            <pspReference>2714166655555850</pspReference> 
            <reason>Cardholder does not recognise</reason> 
            <success>true</success> 
          </notificationRequestItem> 
        </notificationItems> 
      </ns1:notification> 
    </ns1:sendNotification> 
  </soap:Body> 
</soap:Envelope> 
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:sendNotification xmlns:ns1="http://notification.services.adyen.com">
      <ns1:notification>
        <live xmlns="http://notification.services.adyen.com">true</live>
        <notificationItems xmlns="http://notification.services.adyen.com">
          <notificationRequestItem>
            <additionalData xsi:nil="true"/>
            <amount>
              <currency xmlns="http://common.services.adyen.com">EUR</currency>
              <value xmlns="http://common.services.adyen.com">304</value>
            </amount>
            <eventCode>NOTIFICATION_OF_CHARGEBACK</eventCode>
            <eventDate>2013-04-15T09:12:02.423+02:00</eventDate>
            <merchantAccountCode>TestMerchant</merchantAccountCode>
            <merchantReference>1-6GNEZHGTGT</merchantReference>
            <operations xsi:nil="true"/>
            <originalReference>1805647532335033</originalReference>
            <paymentMethod>directdebit_NL</paymentMethod>
            <pspReference>4679660098811789</pspReference>
            <reason>2013.04.12/08.09.20/821</reason>
            <success>true</success>
          </notificationRequestItem>
        </notificationItems>
      </ns1:notification>
    </ns1:sendNotification>
  </soap:Body>
</soap:Envelope>
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:sendNotification xmlns:ns1="http://notification.services.adyen.com">
      <ns1:notification>
        <live xmlns="http://notification.services.adyen.com">true</live>
        <notificationItems xmlns="http://notification.services.adyen.com">
          <notificationRequestItem>
            <additionalData xsi:nil="true"/>
            <amount>
              <currency xmlns="http://common.services.adyen.com">EUR</currency>
              <value xmlns="http://common.services.adyen.com">4290</value>
            </amount>
            <eventCode>CHARGEBACK</eventCode>
            <eventDate>2014-11-25T07:52:54.669+01:00</eventDate>
            <merchantAccountCode>TestMerchant</merchantAccountCode>
            <merchantReference>YYF5YYC0:4511b9c93pskpx</merchantReference>
            <operations xsi:nil="true"/>
            <originalReference>4814161566397936</originalReference>
            <paymentMethod>sepadirectdebit</paymentMethod>
            <pspReference>1414164315656702</pspReference>
            <reason>MD06:RefundRequestByEndCustomer</reason>
            <success>true</success>
          </notificationRequestItem>
        </notificationItems>
      </ns1:notification>
    </ns1:sendNotification>
  </soap:Body>
</soap:Envelope>
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:sendNotification xmlns:ns1="http://notification.services.adyen.com">
      <ns1:notification>
        <live xmlns="http://notification.services.adyen.com">true</live>
        <notificationItems xmlns="http://notification.services.adyen.com">
          <notificationRequestItem>
            <additionalData xsi:nil="true"/>
            <amount>
              <currency xmlns="http://common.services.adyen.com">EUR</currency>
              <value xmlns="http://common.services.adyen.com">409</value>
            </amount>
            <eventCode>CHARGEBACK_REVERSED</eventCode>
            <eventDate>2013-01-27T05:11:58.634+01:00</eventDate>
            <merchantAccountCode>TestMerchant</merchantAccountCode>
            <merchantReference>1-AWSSVULBWX</merchantReference>
            <operations xsi:nil="true"/>
            <originalReference xsi:nil="true"/>
            <paymentMethod>directdebit_NL</paymentMethod>
            <pspReference>4815580881292917</pspReference>
            <reason>Chargeback reversed</reason>
            <success>true</success>
          </notificationRequestItem>
          </notificationItems>
      </ns1:notification>
    </ns1:sendNotification>
  </soap:Body>
</soap:Envelope>

Retrieve applicable defense reasons

This API call returns a list of applicable defense reasons. These reasons are as specified by the schemes. Also, the documents required to defend the disputes conform the schemes regulations.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <retrieveApplicableDefenseReasons xmlns="http://dispute.services.adyen.com">
      <request>
        <disputePspReference>9913486733050065</disputePspReference>
        <merchantAccountCode>TestMerchant</merchantAccountCode>
      </request>
    </retrieveApplicableDefenseReasons>
  </soap:Body>
</soap:Envelope>
Name Type Required Description
disputePspReference String (tick)

The reference assigned to the dispute.

merchantAccount String (tick)
The merchant account identifier you want to process the (transaction) request with.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns0="http://dispute.services.adyen.com">
  <soap:Body>
    <ns0:retrieveApplicableDefenseReasonsResponse>
      <ns0:response>
        <ns0:defenseReasons>
          <ns0:DefenseReason>
            <ns0:defenseDocumentTypes>
              <ns0:DefenseDocumentType>
                <ns0:available>false</ns0:available>
                <ns0:defenseDocumentTypeCode>MerchandiseDescription</ns0:defenseDocumentTypeCode>
                <ns0:requirementLevel>Required</ns0:requirementLevel>
              </ns0:DefenseDocumentType>
            </ns0:defenseDocumentTypes>
            <ns0:defenseReasonCode>AdditionalInformation</ns0:defenseReasonCode>
            <ns0:satisfied>false</ns0:satisfied>
          </ns0:DefenseReason>
        </ns0:defenseReasons>
        <ns0:disputeServiceResult>
          <ns0:success>true</ns0:success>
        </ns0:disputeServiceResult>
      </ns0:response>
    </ns0:retrieveApplicableDefenseReasonsResponse>
  </soap:Body>
</soap:Envelope>
Name Type Returned by default Description
defenseReasons class (tick)

A list of defense reasons that are applicable to the dispute.

It can contain one or more children of type.

  • defenseReason
defenseReason class (tick)

A container for a defense reason.

This field takes the following children:

  • defenseReasonCode
  • satisfied
  • defenseDocumentTypes
defenseReasonCode String (tick)

A code identifying the defense reason.

If required, a full list of defense reasons codes can be requested to the Adyen Support (support@adyen.com).

satisfied Boolean (tick)

A flag indicating if sufficient defense material has been supplied to defend the dispute with the given defense reason.

defenseDocumentTypes

class  

A specified list of defense document types that can be submitted to the schemes for the defense reason.

It can contain one or more children of type.

  • defenseDocumentType
defenseDocumentType class (tick)

A container for a defense document type.

This field takes the following children:

  • defenseDocumentTypeCode
  • available
  • requirementLevel
defenseDocumentTypeCode String (tick)

A code identifying the type of defense document requested.

If required, a full list of defense defense document types can be requested from the Adyen Support team (support@adyen.com).

available Boolean (tick)

This is a flag to mark if the document is already present in the dispute service, or still requires submission from the merchant.

requirementLevel

String (tick)

Level of requirement of the documents for a successful defense.

There are three possible values:

  • Required. The document must be supplied.
  • OneOrMore. At least one of the documents with this label must be supplied.
  • Optional. This document is optional to supply.

disputeServiceResult

class (tick)

A container for result of this response.

This field takes the following children:

  • success
  • errorMessage
success Boolean (tick) Success of the operation. In case of no success an error message will be given in the next field.
errorMessage String (error)

A textual description of the error.

Supply dispute defense documents

This API call allows you to submit all relevant defense material for the dispute.

The supplied defense documents are not sent automatically to the issuer. This will only be done with the final defend dispute API call.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <supplyDefenseDocument xmlns="http://dispute.services.adyen.com">
      <request>
        <defenseDocuments>
          <DefenseDocument>
            <content>CTWFuIGlzIGRpc3Rpbmd1aXNoZWQs.....</content>
            <contentType>image/jpeg</contentType>
            <defenseDocumentTypeCode>MerchandiseDescription</defenseDocumentTypeCode>
          </DefenseDocument>
        </defenseDocuments>
        <disputePspReference>9913486733050081</disputePspReference>
        <merchantAccountCode>TestMerchant</merchantAccountCode>
      </request>
    </supplyDefenseDocument>
  </soap:Body>
</soap:Envelope>

 

Name Type Required Description
disputePspReference String (tick)

The reference we have assigned to the dispute.

merchantAccount String (tick)
The merchant account identifier you want to process the (transaction) request with.
defenseDocuments Object (tick)

A container of list of defense documents.

It can contain one or more children of type

  • defenseDocument
defenseDocument Object (tick)

A container of defense document to supply.

This field takes the following children:

  • defenseDocumentTypeCode
  • contentType
  • content
defenseDocumentTypeCode String (tick)

One of the defense document type codes you obtained in the Retrieve Applicable Defense Reasons response.

In addition to predefined document types you can also provide a generalized defense document type. If you need to configure this functionality for your account, contact the Adyen Support Team.

Once this feature is enabled, you can supply a generic defense document to the schemes for the defense reason. When supplying such documents, set the defenseDocumentTypeCode property to AlternativeDefenseMaterial.

contentType String (tick)

The content type of the document.

Possible values are:

  • image/jpg
  • image/jpeg
  • image/tiff
  • application/pdf
  • text/clearing
content Base64 binary (tick)

The content of the document in Base64 Binary format.

It must be in the format specified in the field contentType.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns0="http://dispute.services.adyen.com">
  <soap:Body>
    <ns0:supplyDefenseDocumentResponse>
      <ns0:response>
        <ns0:disputeServiceResult>
          <ns0:success>true</ns0:success>
        </ns0:disputeServiceResult>
      </ns0:response>
    </ns0:supplyDefenseDocumentResponse>
  </soap:Body>
</soap:Envelope>
Name Type Returned by default Description

disputeServiceResult

Object (tick)

A container for result of this response.

This field takes the following children:

  • success
  • errorMessage
success Boolean (tick)

Success of the operation. 

In case of no success an error message will be given in the next field.

errorMessage String (error)

A textual description of the error.

 

Delete dispute defense document

Before defending the dispute, it is possible to delete defense documents that were submitted previously.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <deleteDisputeDefenseDocument xmlns="http://dispute.services.adyen.com">
      <request>
        <disputePspReference>9913486733050081</disputePspReference>
        <merchantAccountCode>TestMerchant</merchantAccountCode>
        <defenseDocumentType>image/jpeg</defenseDocumentType>
      </request>
    </deleteDisputeDefenseDocument>
  </soap:Body>
</soap:Envelope>
Name Type Required Description
disputePspReference String (tick)

The reference we have assigned to the dispute.

merchantAccount String (tick)
The merchant account identifier you want to process the (transaction) request with.

defenseDocumentType

String (tick)

The defense document type code supplied in the Retrieve Applicable Defense Reasons request.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.or/2001/XMLSchema-instance" xmlns:ns0="http://dispute.services.adyen.com">
  <soap:Body>
    <ns0:deleteDefenseDocumentResponse>
      <ns0:response>
        <ns0:disputeServiceResult>
          <ns0:success>true</ns0:success>
        </ns0:disputeServiceResult>
      </ns0:response>
    </ns0:deleteDefenseDocumentResponse>
  </soap:Body>
</soap:Envelope>
Name Type Returned by default Description

disputeServiceResult

class (tick)

A container for result of this response.

This field takes the following children:

  • success
  • errorMessage
success Boolean (tick)

Success of the operation. 

In case of no success an error message will be given in the next field.

errorMessage String (error)

A textual description of the error.

Defend dispute

This the final call that you should perform to the dispute service. After you have completed all the steps, the real dispute defense takes place with all the submitted documentation.

Remember to make this call only after you have supplied all relevant documents that helps you defend the dispute.

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <defendDispute xmlns="http://dispute.services.adyen.com">
      <request>
        <defenseReasonCode>AdditionalInformation</defenseReasonCode>
        <disputePspReference>9913486733050081</disputePspReference>
        <merchantAccountCode>YourMerchant</merchantAccountCode>
      </request>
    </defendDispute>
  </soap:Body>
</soap:Envelope>
Name Type Required Description
disputePspReference String (tick)

The reference assigned to the dispute.

merchantAccount String (tick)
The merchant account identifier you want to process the (transaction) request with.

defenseReasonCode

String (tick)

The defense reason selected by the merchant to defend the dispute.

Response:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns0="http://dispute.services.adyen.com">
  <soap:Body>
    <ns0:supplyDefenseDocumentResponse>
      <ns0:response>
        <ns0:disputeServiceResult>
          <ns0:success>true</ns0:success>
        </ns0:disputeServiceResult>
      </ns0:response>
    </ns0:supplyDefenseDocumentResponse>
  </soap:Body>
</soap:Envelope>
Name
Type
Returned by default
Description

disputeServiceResult

class (tick)

A container for result of this response.

This field takes the following children:

  • success
  • errorMessage
success Boolean (tick)

Success of the operation. 

In case of no success an error message will be given in the next field.

errorMessage String (error)

A textual description of the error.

Test applicable dispute reasons

 You can test the dispute reasons by following the below steps:

  1. In a payment request, set the cardholderName to chargeback and provide the ReasonCode in the cardholderName field following chargeback separated by a colon. Example: 

    chargeback:30
  2. Submit the request for authorization. 
    It usually takes upto 24 hrs for a request to become a chargeback.
  3. After the chargeback is created, retrieve the applicable dispute reason using the Retrieve defense reasons call.
  4. Submit the dispute.
  5. Confirm and defend dispute using Defend dispute call.
    You receive a confirmation.

A flag can be set to either win or lose the dispute.  

Request:

{
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "8",
    "expiryYear": "2018",
    "cvc": "737",
    "cardholderName": "chargeback:30"
  },
  "amount": {
    "value": 1500,
    "currency": "EUR"
  },
  "reference": "payment-2016-11-1-13",
  "merchantAccount": "NewCoCOM"
}