There may be times when one of your cardholders may disagree with a transaction charged to their Adyen-issued card. If a merchant refuses to make a refund directly to them, the cardholder can request a chargeback through the card scheme by raising a dispute.
It's also a requirement for your cardholder to report any fraudulent transactions made on their card. 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.
You can raise a dispute for any captured payment using the Raise disputes API.
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, 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.
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.
Requirements
Before you begin, take into account the following requirements.
| 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 you want to raise a dispute for a chargeback or for a report of fraudulent activity.
If you suspect your card has been lost or stolen, make sure to close the card. - Raise a dispute for one of the following dispute types:
- fraud - The transaction was fraudulent.
- notDelivered - Goods or services were not delivered.
- Optionally provide supporting information for your dispute as attachments.
- Review the information in the dispute.
- Update the status of your dispute to submitted or closed.
- Watch dispute webhooks for status changes to your submitted dispute, or view the status of your 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 15 disputes that they can raise over the course of their possession of their card. You can raise a dispute for one of the following dispute reasons.
| Dispute reason | Dispute type | Timeline | Information | Suggested attachments |
|---|---|---|---|---|
| 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. |
|
|