Issuin icon

Bulk-upload disputes

Learn how to use the Balance Platform Customer Area to upload multiple disputes and their supporting information.

This feature is in pilot phase. To enable this feature in your platform, reach out to your Adyen contact.

You can use the Balance Platform Customer Area to raise multiple disputes, along with attachments of supporting information. Examples of supporting information are screenshots or photos of receipts, email communication with the merchant, or any other information the card scheme can review to make a decision on the dispute.

To submit disputes, compile dispute information in a CSV file, package it with the necessary supporting information attachments in a ZIP file, and upload it to the upload it to the Balance Platform Customer Area.

This feature is designed for card partners who prefer a UI-based workflow to raise disputes. If you want to have more control over the dispute process, we recommend using the Raise disputes API.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Requirement Description
Integration type Issuing
Customer Area roles To access the Upload disputes menu in the Balance Platform Customer Area, make sure that you have the following role:
  • Manage issuing disputes
    Webhooks Subscribe to the following webhook(s):

    Prepare the ZIP file

    Your upload must be a single ZIP file containing:

    • A CSV file named disputes.csv that contains information about each dispute.
    • All the attachments that the csv references.

    The total uncompressed size of all the files must be less than 100 MB. Once compressed, the ZIP cannot be larger than 50 MB.

    1. Create the disputes.csv file

    To ensure your CSV file is formatted correctly and has the right columns, use the disputes.csv template. The template includes an example dispute for each dispute type.

    For each dispute you want to raise, add a row to your disputes.csv file. Provide data for all columns that pertain to the dispute type. For example, if you are raising a dispute with the type fraud, enter data in the General columns and the columns for fraud. Make sure to leave all remaining columns empty for that row.

    General columns

    Input data into the following columns for every dispute:

    Column Name Description Values required
    transactionId The transaction ID of the Booked event for the transaction you want to dispute. This can be found in the Customer Area Transfer Details page, or in the Balance Platform Accounting Report.
    Note: the transaction ID is different from the transfer ID.    		 -white_check_mark-
    description Your description of the dispute. You can use this field as an internal reference.
    Maximum length: 50 characters.
    type The category of the dispute. This determines which other type-specific columns you need to enter in a row.
    Accepted values:
    • notDelivered
    • fraud
    • duplicate
    		 -white_check_mark-
    disputedAmount_currency The three-character ISO 4217 currency code for the disputed amount. For example, enter USD for United States Dollars or EUR for Euro. If you leave this field empty, the full amount is used for the dispute.
    disputedAmount_value The value of the disputed amount in minor units. For example, enter 12500 for $125.00. If you leave this field empty, the original currency is used for the dispute.
    attachment_fileName The file name for the supporting information attachment, including its extension. Leave blank if there is no attachment for this dispute row. Supported file types: PDF, JPEG, TIFF.
    Maximum length: 17 characters.
    attachment_attachmentType The type of information in the attachment. Required if attachment_fileName is provided. Leave blank if there is no attachment.
    Accepted values:
    • receipt
    • correspondence
    • other

    Type-specific columns

    Enter values in the columns that relate to the specific type of the dispute you are raising. Leave all other columns empty.

    If the type for a dispute is notDelivered, enter values in the following notDeliveredInfo columns for that row.

    Leave all other dispute type info (fraudInfo, duplicateInfo) columns empty for that row.

    Column Name Description
    notDeliveredInfo_descriptionOfIssue Your description of the problem.
    Maximum length: 2500 characters.
    notDeliveredInfo_whatWasNotDelivered A type indicating what the payment was for.
    Accepted values:
    • goods
    • services
    notDeliveredInfo_lastExpectedDate The date the undelivered goods or services were expected to be delivered. Use YYYY-MM-DD format.
    notDeliveredInfo_whoCancelled A type indicating the party that initiated the cancellation of the transaction.
    Accepted values:
    • merchant
    • cardholder
    notDeliveredInfo_dateOfCancellation The date the undelivered goods or services were cancelled. Use YYYY-MM-DD format.
    notDeliveredInfo_agreedDeliveryLocation The delivery location specified by the cardholder.
    Maximum length: 500 characters.
    notDeliveredInfo_deliveredToWrongLocation Indicates goods were delivered to the wrong location.
    Accepted values:
    • true
    • false
    notDeliveredInfo_didCardholderReturn Indicates if the cardholder returned the goods to the merchant.
    Accepted values:
    • true
    • false
    notDeliveredInfo_isDeliveryLate Indicates if the goods or services were delivered late.
    Accepted values:
    • true
    • false
    notDeliveredInfo_isMerchantBankrupt Indicates if the transaction was processed by a bankrupt merchant.
    Accepted values:
    • true
    • false
    notDeliveredInfo_isNonFiatOrNft Indicates if the transaction is non-fiat or non-fungible token (NFT) related.
    Accepted values:
    • true
    • false

    If the type for a dispute is fraud, enter values in the following notDeliveredInfo columns for that row.

    Leave all other dispute type info (notDelivered, duplicateInfo) columns empty for that row.

    Column Name Description
    fraudInfo_cardDoesNotBelongToCardholder Indicates if the card is no longer in the cardholder's possession.
    Accepted values:
    • true
    • false
    fraudInfo_cardWasCounterfeited Indicates if the card was counterfeited.
    Accepted values:
    • true
    • false
    fraudInfo_descriptionOfIssue Your description of the issue.
    Maximum length: 2500 characters.
    fraudInfo_reportOnly Set to true if you want to submit a fraud report with no further action. If set to true, there is no request for a chargeback or fee reversal. Default is false.
    Accepted values:
    • true
    • false

    If the type for a dispute is duplicate, enter values in the following notDeliveredInfo columns for that row.

    Leave all other dispute type info (notDeliveredInfo, fraudInfo) columns empty for that row.

    Column Name Description
    duplicateInfo_duplicateTransactionId The transaction ID of the other payment that your cardholder considers to be a duplicate.
    Accepted values:
    • true
    • false
    duplicateInfo_sameCard An indicator if the duplicate transaction occurred on the same card.
    Accepted values:
    • true
    • false
    duplicateInfo_sameIssuer An indicator if the duplicate transaction involved the same issuer.
    Accepted values:
    • true
    • false

    2. Collect your supporting information attachments

    For each row in your CSV file, you can include an attachment file in the root of the ZIP file to be used as supporting information, also known as evidence, for the dispute. The attachments can be a receipt, correspondance with the merchant, or anything else that the cardholder would like to include to support the cardholder's case.

    Adyen supports JPEG, TIFF, and PDF attachments. Each attachment can be up to 2 MB with a file name up to 17 characters, including its extension. You can attach 49 files per upload. The total file size, including all supporting information attachments and the CSV, must not exceed 100 MB before it is compressed.

    3. Create the ZIP file

    After you create your CSV and collect your supporting information attachments, compress the files into a ZIP archive. Place all files at the root of the archive. All subfolders are ignored.

    Example ZIP file structure:

    Example.zip
├─ disputes.csv
├─ evidence_1.jpg
├─ evidence_2.pdf
├─ evidence_3.jpg
└─ evidence_4.tiff

    Before you compress the files, check that they do not exceed 100 MB in total. Then, compress the files into a ZIP archive and make sure the ZIP file does not exceed 50 MB.

    Upload the ZIP file

    When your ZIP file is ready, you can upload it in the Balance Platform Customer Area.

    1. Log in to your Balance Platform Customer Area and navigate to Issuing > Disputes.
    2. Select Upload disputes.
    3. On the upload page, drag and drop your ZIP file or select Browse files to choose it from your computer.
    4. Select Submit.

    If there are no issues with the file type and size you upload, Adyen processes the disputes. You can submit up to ten uploads per day. If you receive an error, check your Zipped file, and try to upload your file again.

    Adyen processes each dispute in your upload individually. To track the result of each dispute, use Dispute webhooks. For more information about tracking disputes, see Associating IDs throughout the dispute lifecycle.

    See also