As a platform that issues cards through Adyen, you must be able to raise disputes on behalf of your cardholders.
These are situations when you need to raise a dispute:
- The cardholder disagrees with a transaction charged to their Adyen-issued card.
If a merchant refuses to make a refund directly to your cardholder, the cardholder can raise a dispute for a chargeback through your UI. - The cardholder reports fraudulent transactions.
If a cardholder realizes their card was lost or stolen, and transactions were charged to their card, you should close their card immediately and report those fraudulent transactions to the card scheme.
To raise disputes for Adyen to submit to card schemes you can:
- Provide a UI for your cardholders to ask for their money back and to report fraudulent transactions and lost cards using the Raise disputes API
- Package dispute details and supporting information into a zip file and upload them through the Customer Area.
You can raise a dispute for any captured payment.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
| Requirement | Description |
|---|---|
| Integration type | Issuing Integration |
| API credential roles | Make sure that you have the following webservice role:
|
| Balance Platform Customer Area roles | Make sure that you have the following role to view disputes:
|
| Webhooks | Subscribe to the following webhook(s):
|
How it works
- Locate the transactionId for which your cardholder wants to raise a dispute for a chargeback or for a report of fraudulent activity.
If you suspect your cardholder's card has been lost or stolen, make sure to close the card. - Raise a dispute for one of the following dispute types:
- duplicate - The transaction was a duplicate charge.
- fraud - The transaction was fraudulent.
- notDelivered - Goods or services were not delivered.
- Optionally provide supporting information for the dispute as attachments.
- Present the information in the raised dispute to your cardholder for review.
- Update the status of the cardholder's dispute to submitted or closed.
If you are raising disputes in the Customer Area, this step is not required. - Watch dispute webhooks for status changes to the submitted dispute, or view the status of disputes in the Balance Platform Customer Area.
- Watch transfer webhooks for the movement of funds due to a chargeback or second chargeback, or view them in the Balance Platform Accounting Report.
Dispute reasons and their types
Cardholders have a maximum limit of 35 disputes that they can raise over the course of their possession of their card. Cardholders can raise a dispute for one of the following dispute reasons.
| Dispute reason | Dispute type | Timeline | Information | Suggested attachments |
|---|---|---|---|---|
| Transaction was a duplicate charge | duplicate | 120 days from the date of the authorized transaction. |
|
|
| Transaction was fraudulent | fraud | 120 days from the date of the authorized transaction. |
|
|
| Goods or services were not delivered | notDelivered | 120 days from the date that goods or services should have been delivered. |
|
|
Lifecycle of a raised dispute
A dispute has the following lifecycle, which you can follow through status changes in dispute webhooks. When you raise a dispute on behalf of a cardholder, Adyen creates an ID for the dispute, and informs your system with a balancePlatform.dispute.created webhook. The initial status of a raised dispute is draft. However, if you raised the dispute by uploading a file in the Customer Area, Adyen automatically updates the status to submitted once it is processed.
While the status of the dispute is draft, your cardholder may change the status of the dispute to closed for any reason.
When your cardholder is satisfied with the information for the dispute, they must change the status of the dispute to submitted. Adyen then packages the dispute and sends it to the card scheme for review.
Whenever there is a change of status for a raised dispute, Adyen informs your system with a balancePlatform.dispute.updated webhook.
| Dispute status | Description |
|---|---|
| draft | A dispute ID was created for the raised dispute, but the status of the dispute has not been set to submitted or closed.You can still edit a dispute with a draft status. |
| closed | The status of the raised dispute is closed.You cannot edit, reopen, or submit a closed dispute. Possible reasons for a closed status are:
|
| submitted | The cardholder reviewed and submitted the dispute to Adyen to process with the card scheme. |
| chargeback | The funds were returned to your dispute account. |
| won | The acquirer can no longer challenge the dispute. The timeline for challenging a dispute is different for each card scheme:
|
| secondChargeback | The funds have been returned to the acquirer. |
Associating IDs throughout the dispute lifecycle:
Adyen informs your system of any updates to the status of your raised disputes with balancePlatform.dispute.updated webhooks. You can follow the dispute throughout its lifecycle by paying attention to the status of the dispute and by correlating the transactionId, the dispute ID, and the Acquirer Reference Number (arn).
- arn: The Acquirer Reference Number (
arn) is a unique number assigned to a card transaction when it goes from the merchant's bank (acquirer) through the card scheme at the cardholder's bank (issuer). - id: Unique ID for the dispute that Adyen creates when you raise a dispute for a card transaction.
- transactionId: The Adyen event ID for the capture that you use to raise the dispute.
Additionally, if the status of your dispute is chargeback or secondChargeback, there is a balance mutation on the Disputes balance account.
When there is a balance mutation, Adyen informs your system with a balancePlatform.transfer.created webhook with the following category, type, and status event mapping:
| Event | category | type | status |
|---|---|---|---|
| chargeback | issuedCard | payment | chargeback |
| secondChargeback | issuedCard | payment | secondChargeback |
This event mapping for chargebacks and second chargebacks is also reflected in the Balance Platform Accounting Report. The ARN is the common link between the original transaction, the raised dispute, and the chargeback/second chargeback transfers. You can locate the ARN in the reference parameter of the balancePlatform.transfer.created webhook Adyen sends to your server.