Dispute API

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. Depending on the payment method used by the shopper, the stage and the reason of the dispute, it may be possible to defend the dispute by supplying appropriate defense material via Adyen. 

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

  • The transaction was made through a 3D Secure authentication
  • Bank transfers

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 choose to ignore an RFI, you have fewer options to defend the dispute and a possible chargeback. A transaction receipt or an invoice is a valid document 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 a 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.


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.


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


  • If the merchant supplies inadequate information to defend the chargeback, 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 returns 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 defend the dispute by selecting a defense reason and by supplying the required documents. After this call, the dispute service sends the defense material to the schemes.

See also