Notification of fraud disputes

There are circumstances when the holder of an Adyen-issued card may need to report fraudulent activity, or register that their card has been lost or stolen. This can happen regardless of whether the card is a physical or virtual card.

If a cardholder notices any fraudulent transactions, close the card and submit fraud disputes for those transactions. Even if no fraudulent transactions have occurred, close a suspected lost or stolen card immediately.

Raise a dispute for fraud

1. Find the transaction ID for which you want to raise a dispute for fraud.
   You can find a transaction ID in one of the following locations:

   • within the Balance Platform Accounting Report
   • from the Balance Platform Customer Area
   • from Transfer webhooks

2. Make a POST /disputes request, specifying the following parameters:

   Parameter	Type	Required	Description
   description	string	no	Your description for the dispute. The description appears in dispute webhooks as pass-through information. Do not include any personally-identifiable information (PII) in this field. Maximum length, 50 characters.
   fraudInfo	object	yes	The object containing additional information for raising a dispute of type fraud. Required for disputes of type fraud.
   fraudInfo.cardDoesNotBelongToCardholder	boolean	yes	The card is no longer in the cardholder's possession. Set to true if the card is lost or stolen. Possible values: true, false.
   fraudInfo.cardWasCounterfeited	boolean	yes	The card was counterfeited. Possible values: true, false.
   fraudInfo.descriptionOfIssue	string	yes	Your description of the issue for raising a dispute of type fraud. Maximum length, 2500 characters.
   fraudInfo.reportOnly	boolean	no	Set to true to instruct Adyen to submit a report of fraud dispute with no further action, such as a request for a chargeback or fee reversal. The default value is false.
   transactionId	string	yes	The unique reference of the transaction for which you are raising the dispute.
   type	string	yes	The type of the dispute. When raising a dispute for fraud, the value must be fraud.

3. Make a note of the dispute id in the response. You need this ID to provide supporting information as an attachment, update the dispute, submit the dispute for an instance of fraud, close the dispute, and follow the lifecycle of the dispute.

   The response includes the following additional parameters:

   Parameter	Type	Description
   arn	string	The unique Acquirer Reference Number (arn) generated by the card scheme for each capture. You can use the arn to trace the transaction through its lifecycle.
   id	string	The unique identifier of the raised dispute.
   status	string	The current status of the dispute. You can update a dispute to submitted or closed. Possible values: draft, submitted, closed, won, chargeback, secondChargeback.

   Adyen sends a balancePlatform.dispute.created webhook to your server for the dispute with a status of draft.

Upload attachments (optional)

We recommend that your cardholder upload supporting documentation, such as receipts, communication with a merchant, or any additional documents that would help the card scheme when they are reviewing the dispute.

1. Make a POST /disputes/{disputeId}/attachments request, specifying the disputeId as a path parameter and the following request parameters.

   Parameter name	Type	Required	Description
   attachmentType	string	yes	The type of information contained in the attachment. Possible values: receipt correspondence other
   fileName	string	yes	The name of the attachment, including its filename extension. Minimum length: four characters, Maximum length: 17 characters, including the extension type. Supported filename extensions: jpeg pdf tiff Examples: airfare24_03.jpeg hotel24_0315.jpeg
   content	string	yes	The content of the image. An attachment must be Base64-encoded data.

2. In the response, note the attachmentId. You may need the ID if you want to later get the attachment, or delete the attachment.

   Parameter name	Type	Description
   attachmentId	string	The unique identifier of the attachment.

Review the dispute

Present the details of the dispute to your cardholder. This allows the cardholder time to make sure they have captured all information correctly before they submit the dispute to the card scheme to review.

1. Make a GET /disputes/{id} request, specifying the dispute id as a request parameter.

Edit dispute details (optional)

If the cardholder wants to make any changes to the information they provided in their dispute, you can make a request to update the dispute.

1. To update information in your dispute, make a PATCH /disputes/{id} request, specifying the dispute id as a path parameter, and supplying updated information in the following request parameters:

   You do not have to provide the complete dispute object in your PATCH request.

   Parameter	Type	Description
   fraudInfo	object	The object containing additional information for raising a dispute of type fraud. Required for disputes of type fraud.
   fraudInfo.cardDoesNotBelongToCardholder	boolean	The card is no longer in the cardholder's possession. Set to true if the card is lost or stolen. Possible values: true, false.
   fraudInfo.cardWasCounterfeited	boolean	The card was counterfeited. Possible values: true, false.
   fraudInfo.descriptionOfIssue	string	Your description of the issue for raising a dispute of type fraud. Maximum length, 2500 characters.
   fraudInfo.reportOnly	boolean	Set to true to instruct Adyen to submit a report of fraud dispute with no further action, such as a request for a chargeback or fee reversal. The default value is false.
   status	string	The status of the dispute. You can update the status of a raised dispute from draft to submitted or closed. Possible values: submitted, closed.

2. Present the updated dispute details from the response to your cardholder.

Submit the dispute

If your cardholder is satisfied with the information they provided for the dispute, they can submit the dispute to the card scheme for review and a chargeback, if successful.

When you submit a dispute to the card scheme, you can no longer update the dispute, upload or delete attachments, or close the dispute.

1. Make a PATCH /disputes/{id} request, specifying the dispute id as a path parameter, and include status with a value of submitted as a request parameter.

2. A successful response includes the dispute object, with an updated status of submitted. Adyen also sends your system a balancePlatform.dispute.updated webhook with the updated status.

3. Notify your cardholder that they have successfully submitted their dispute.

Process webhooks for status changes

1. Process balancePlatform.dispute.updated webhooks, looking for changes in the status of your raised dispute.

2. If the status of a dispute changes to chargeback or secondChargeback, inspect balancePlatform.transfer.created webhooks for the matching Acquirer Reference Number (arn), and reconcile balances for the cardholder's balance account.

   Lifecycle of a raised dispute describes in more detail how status changes for disputes are communicated to your system through Adyen webhooks, and how balance mutations are recorded in the Balance Platform Accounting Report.

See also