/
15 minute read
April 22, 2022

Disputes in the Dashboard (Beta)

Note
This feature is currently in beta and subject to change. It also requires additional activation steps. To learn more about the Beta program for this feature and about activating it for your program, contact your Marqeta representative.

Use Disputes in the Marqeta Dashboard to:

  • Create a dispute.

  • Manage dispute progress.

  • Transition a dispute.

  • Create and manage disputes in bulk.

For general information on disputes, the dispute lifecycle, chargebacks, and best practices, see About Disputes.

The basics

To manage disputes, log into the Marqeta Dashboard and select RiskControl > Disputes from the sidebar. For more on accessing the Marqeta Dashboard, see Accessing the Marqeta Dashboard.

Viewing current disputes

To view the current disputes, go to RiskControl > Disputes. The current disputes are displayed in the Dispute queue tab.

View current disputes

Is this helpful?

Yes
No

Default columns are displayed. To modify the displayed columns, see Setting the columns to display and column order.

Field Description

Last modified

The date and time when the dispute case was most recently modified.

Next steps

The action required to move the dispute to the next state.

Case state

The current state of the dispute case: Open, Open action required, Ready, Initiated, or Closed.

Integrated

Indicates whether the dispute is integrated or non-integrated with the network. An integrated dispute is directly connected with the network and is be automatically updated as the network makes updates. A non-integrated dispute is not directly connected with the network and requires manual handling, such as checking the network portal and adding manual entries.

Case token

The token identifying the dispute case.

Cardholder name

The name of the cardholder who is disputing the transaction.

Business token

The token identifying the business.

Transaction token

Original transaction token. This must be the token from a cleared (settled) transaction, not an authorization token.

Dispute reason

The reason for the current dispute state.

Dispute amount

Amount disputed. If the cardholder has disputed only a portion of the original transaction amount, this will be a partial amount.

Next actor

The next actor whose action is required to move the dispute to the next state.

Days to act

The remaining days for a customer to act before losing the capability to act or certain rights related to the transaction.

Network case status

The current network dispute status.

Network case number

The reference number provided by the network (the network dispute ID).

Case assignee

The user assigned to the case.

Currency

The currency of the disputed amount.

Time created

Timestamp of the original transaction. This is not required to process a dispute, but could prove vital for file grooming and manual dispute review.

Searching for users, businesses, cards, or disputes

Use the Search bar at the top of the view area to search for users, businesses, cards, or dispute cases. You can search for users by account number or user token. For businesses, cards, and dispute cases, search by token.

To use the Search bar:

  • Enter the token in the search box and select Search.

    Search bar

    Is this helpful?

    Yes
    No
  • Select the item in the search result below the search box. The requested entity opens in the appropriate area of the Dashboard.

Filtering disputes

You can filter disputes by case state, transaction or cardholder token, dispute amount, case assignee, dispute reason, reason code, actor, or whether a dispute is integrated. You can sort by created time or time modified.

To filter disputes:

  • In RiskControl > Disputes, select Filter table.

  • Enter the values you want to use for the filter.

    Disputes filter

    Is this helpful?

    Yes
    No
  • Select Filter.

You can also filter disputes by where they are in the dispute lifecycle by selecting which disputes to view from the drop-down box to the right of Filter table box:

  • All disputes - All current disputes.

  • Frontend intake - Disputes in the Ready, Open, or Open action required state.

  • Backend resolution - Disputes that have been sent to the network.

  • Resolved - Disputes that are resolved.

Setting the columns to display and column order

To customize the column display:

  • In RiskControl > Disputes, select the gear icon in the upper-right corner of the list, and choose Modify columns.

  • In Customize Columns, select the columns you want to display.

  • To change the display order, select and hold the row and move it to the new position.

  • Choose Save.

To reset the column display, select the Reset table to default option from the gear icon.

Viewing dispute details

In Dispute details, you can update the dispute details, view cardholder information, view a transition history, or mark the dispute case as ready. For details on how to do this, see Managing Dispute Cases.

Note
The specific details displayed vary depending on the current state of the dispute case.

To view dispute details:

  • Go to RiskControl > Disputes and select the dispute, or select See details from the vertical ellipsis icon at the right of the row. Details are displayed in the Submission details tab.

    View dispute details

    Is this helpful?

    Yes
    No

    Dispute details include:

    Field Description

    Network case ID

    The reference number provided by the network.

    Next actor

    The next actor whose action is required to move the dispute to the next state.

    Days to act

    The remaining days for a customer to act before losing the capability to act or certain rights related to the transaction.

    Network case status

    For submitted cases, the current state of the dispute on the network.

    Case assignee

    The user assigned to the case.

    Dispute amount

    Amount disputed. If the cardholder has disputed only a portion of the original transaction amount, this will be a partial amount.

    Dispute reason

    The reason for the dispute.

    Purchase description and dispute explanation

    Detailed description of the purchase and explanation for the dispute.

    Expected receipt date

    The expected receipt date.

    Expected receipt time

    The expected receipt time.

    Cardholder canceled prior to the expected date

    Indicates whether the cardholder canceled before the expected date.

    Cancellation Date

    The cancellation date.

    Acquirer reference number (ARN)

    The acquirer reference number.

    Label

    Additional information related to resolving the dispute.

    Notes

    Any useful notes about the transaction.

    Transaction details

    Any clarifying details about the transaction.

    Merchant details

    Details of the merchant involved in the transaction.

  • To see detailed information about the transaction including cardholder information, select the arrow in front of Transaction details to the right of the view area.

  • To view point-of-sale details, select the arrow in front of Point of Sale details in the lower right.

To view related transactions:

  • In the sidebar, select RiskControl > Disputes.

  • Select the dispute or select See details from the vertical ellipsis icon at the right of the row.

  • Select the Related transactions tab.

    View related transactions

    Is this helpful?

    Yes
    No

Viewing dispute case transition history

To view a transition history:

  • In the sidebar, select RiskControl > Disputes.

  • Select the dispute or select See details from the vertical ellipsis icon at the right of the row.

  • Select the Transition history tab.

    View transition history

    Is this helpful?

    Yes
    No

Creating a dispute case

Transactions can be disputed if they are in either a cleared or completion state. When you create a dispute case, you will need to provide dispute details and upload required documents. You can create a dispute case from the Users list or from the Disputes queue.

To create a dispute from the Users list:

  • From the sidebar, select Customers > Users, then select the user. To search for a user, select Filter.

  • Do either of the following:

    • Select the Transactions tab. To search for the transaction, select Filter.

    • Select the Cards tab, select the card from the list of cards, and then select the Card transactions tab. To search for the transaction, select Filter.

  • Select vertical ellipsis at the far right of the row and select Dispute.

  • Select either Full transaction amount if the entire amount is being disputed, or select Other amount and enter the amount being disputed.

  • Select a dispute reason or enter a reason code.

  • Depending on the dispute reason, specify the details of the dispute. Specify the means of payment with sufficient transaction details to allow the merchant to locate the transaction.

  • Select Create dispute.

  • To continue with the case, select Continue. To return to Transactions or Card Transactions, select Return to transactions.

To create a new dispute from the Disputes queue:

  • From the sidebar, select RiskControl > Disputes.

  • Select Create manual case, enter the token for the transaction you would like to dispute, and select Continue.

  • Select either Full transaction amount if the entire amount is being disputed, or select Other amount and enter the amount being disputed.

  • Select a dispute reason or enter a reason code.

  • Depending on the dispute reason, specify the details of the dispute. Specify the means of payment with sufficient transaction details to allow the merchant to locate the transaction.

  • Select Create dispute.

Creating dispute cases in bulk

With bulk uploads you can upload multiple cases using a bulk file in .xlxs format that contains the information for each case. Bulk uploads bypass the typical dispute creation process, moving the case state directly to the initiated state. Because records in a bulk file must conform to exact file formatting, using bulk uploads may require additional maintenance.

After dispute cases are successfully uploaded in a bulk file, each case can be managed using the procedures described in Managing dispute cases.

Note
Only Visa fraud and authentication disputes can be submitted in bulk. All other disputes must be individually created and submitted, as described in Creating a dispute case.

To submit dispute cases in bulk:

  • Download the template.

  • Create the bulk upload file.

  • Create the object rows.

  • Upload the file.

  • View the failure report.

Each of these steps is described in detail in the following sections.

Download the template

To download the template:

  • In RiskControl > Disputes, select the Bulk upload tab.

  • Select template, highlighted in blue, in the introductory paragraph.

Create the bulk upload file

Using the template, create and populate your upload file. When naming your upload files, avoid special characters and spaces in the file name. Use unique file names. You cannot upload the same file with the same name multiple times.

Include only Fraud and Authorization disputes in the file. For each dispute, include the clearing transaction token in the TRANSACTION_TOKEN field. All fields other than MEMO are required. Smaller files result in faster upload times. The file must include the following fields:

Field Description

TRANSACTION_TOKEN

Original transaction token. This must be the token from a cleared (settled) transaction, not an authorization token.

CREATED_AT

Timestamp of the original transaction. This is not required to process a dispute, but could prove vital for file grooming and manual dispute review.

DISPUTE_AMOUNT

Amount disputed. If the cardholder wants to dispute only a portion of the original transaction amount, include the partial amount here along with a reason in the DISPUTE_AMOUNT_CHANGE_REASON column. You should submit disputes only for disputes greater than the card network’s $25 threshold amount.

Note: Do not include any special characters such as a currency symbol. Format: 00.00

REASON_CODE

Reason code, which can be one of the following, regardless of the card network:

NOT_AUTHORIZED_CARD_PRESENT, NOT_AUTHORIZED_CARD_ABSENT, NO_AUTHORIZATION

MERCHANT_NAME

Name of the merchant. This may be useful for researching dispute details, and can be obtained from the authorization event type in the card_acceptor object of the Webhooks endpoint.

DISPUTE_ACTION

The required action—​either CHARGEBACK_CREDIT or CHARGEBACK_NO_CREDIT.

DISPUTE_AMOUNT_CHANGE_REASON

Note explaining the reason for disputing an amount less than the original transaction amount. If the disputed amount is less than the original transaction amount, this reason is required by the network.

Upload the file

To upload the bulk file:

  • From the sidebar, select RiskControl > Disputes, then select the Bulk upload tab.

  • Select Browse and choose a bulk upload file that conforms to the .xlxs template.

  • Select Upload. The upload process may take several minutes.

  • If an Unable to upload file error message appears during the upload process, wait a few minutes and try again.

View the failure report

After the Marqeta platform processes your bulk upload file, it generates a failure report containing your complete request along with relevant data for each record in the file. Depending on the size of the upload file, the report may take several minutes to generate.

Completed files appear under Bulk upload history. After uploading a file, select Refresh periodically to see if your uploads have completed. Download the failure report to view any disputes that failed to upload. If the report file is empty, no failures have occurred for that upload.

To view a report:

  • In RiskControl > Disputes, select the Bulk upload tab.

  • Select the Download report link in the Failure Report column. If you do not see the link for the uploaded file, select Refresh and check back after 20 to 30 minutes.

  • Open the downloaded file. The file name is prefixed with REJECTED-, followed by the datetime of the upload, and concatenated to the upload file name. For example, REJECTED-2021-01-19-192915_myuploadfilename. The following information is returned in the .xlxs file for each transaction that failed from the uploaded bulk file:

Field Description

TRANSACTION_TOKEN

Original transaction token from a cleared (settled) transaction.

TRANSACTION_ID

Transaction ID of the transaction being disputed.

CREATED_AT

Timestamp of the original transaction.

REASON_CODE

Reason code, which can be one of the following, regardless of the card network:

NOT_AUTHORIZED_CARD_PRESENT, NOT_AUTHORIZED_CARD_ABSENT, NO_AUTHORIZATION

DISPUTE_AMOUNT

Amount disputed, which may be a portion of the original transaction amount.

DISPUTE_AMOUNT_CHANGE_REASON

Note explaining the reason for disputing an amount less than the original transaction amount. If the disputed amount is less than the original transaction amount, this reason is required by the network.

MEMO

Additional information that was provided in the upload file.

FAILURE_REASON

The reason that this transaction failed to successfully load.

Recovering from unsuccessful uploads

If any disputes have not successfully uploaded from the bulk file, either include these in a new upload file, ensuring that all required information is included and correctly formatted, or manually create the case as described in Creating a dispute case.

Managing dispute cases

After you have created a case, you need to provide any additional information required and move the case along the case timeline to the next case state until the case is resolved. The following are the case states from when the case is opened until it is closed:

Open

The case has been created.

Open action required

The case has been created and requires action before it is ready to be submitted to the network.

Ready

The case is ready to be submitted to the network.

Initiated

The case has been submitted to the network for a decision.

Closed

The case has been resolved and closed.

The current state appears in the State column in the Disputes Queue.

Transitioning a dispute case

The following general steps allow you to enter all the required information, gather the required documents, and submit the case to the network:

  • Review for associated transactions (Visa only).

  • Upload required documentation.

  • Confirm case details and set the case to Ready.

  • Submit the case to the network.

  • Close the case.

The following sections provide details for each step.

Review for associated transactions (Visa only)

The associated transaction table displays any transactions that the network has listed as possibly associated with the current dispute. Up to 500 transactions are displayed from the network.

To review associated transactions that may be duplicates and withdraw them:

  • In the Disputes tab of Dispute details, select Review associated transactions. Transactions that appear to be similar to the dispute information are displayed under Review associated transactions. These are transactions that have a transaction type that are the same as the original transaction.

    Review associated transactions

    Is this helpful?

    Yes
    No
  • Select any associated transactions. Scroll down to view additional transactions, if necessary.

  • If any transactions in the list represent a refund associated with this dispute, select those transactions and select Withdraw and close to withdraw those disputes.

  • If there are no associated transactions, select These transactions are not associated.

  • If the transaction type is credit, provide any useful information in Explanation of credit.

Upload required documentation

Upload any documents related to the case. If a case is submitted without the required documentation, the case could be lost. If a non-Visa method of payment was used, upload documents detailing payment by other means such as a bank statement, canceled check, or receipt.

To upload documents:

  • In Dispute details, select Upload related documents.

  • For each document, select Upload and locate the document. An image of each uploaded document is displayed.

Confirm case details

In this step, confirm case details and get the case ready to submit to the network. Specify any details that were not specified, incomplete, or incorrect, including the means of payment with sufficient transaction details to allow the merchant to locate the transaction.

To confirm the case details:

  • In Dispute Details, select Confirm dispute details, and enter or edit the details as appropriate.

  • For any duplicate transactions, choose the reason for the duplication:

    • Same merchant on the same card

    • Same merchant on a different Visa card owned by the same Issuer/Cardholder

    • Same merchant but paid by other means

  • For partial disputes—that is, if the disputed amount less than the transaction amount—ensure that relevant documents are loaded and enter the disputed amount.

  • Select Mark as ready.

Submit the case to the network

For a case that is in a Ready state, you can send it to the network by choosing Submit to network in the upper-right corner.

You can also submit a case from the Dispute Queue:

  • In the sidebar, select RiskControl > Disputes.

  • Select the vertical ellipsis icon at the right of the row, and choose Submit to network.

Close the case

Once you have received a decision from the network and the case is resolved, you can close the case. To close the case, select Close case.

Reopening a case

If a case has been closed but needs to be reopened. To reopen a case:

  • From the sidebar, select RiskControl > Disputes.

  • From the vertical ellipsis at the right the dispute row, select Reopen case.

Viewing the chargeback report

You can view a chargeback report in the Marqeta Dashboard Reports area. To access the report:

  • Go to Reports in the navigation bar.

  • Select the Risk Monitoring — Chargebacks report.

The dashboard allows you to customize your report to include multiple data fields related to the status of your disputes. For more about viewing reports, see Reports.

Join our developer newsletter