Understand how Moov handles disputes, and the type of information you can receive about them.

A dispute occurs when a cardholder formally questions the validity of a payment by raising a complaint to their card issuer. A dispute can be automatically resolved if a merchant utilizes a pre-dispute service. Otherwise, the card issuer will process a chargeback, temporarily reversing the payment for the duration of the dispute.

Moov currently supports RDR (Visa Rapid Dispute Resolution) decisioned pre-disputes and chargebacks from all card networks.

Dispute handling

Moov engages directly with the card networks and communicates dispute details to you via API and Dashboard. Moov’s customers must pull dispute data and pass it along to their merchants on an ongoing basis.

The chargeback amount can be either a portion of the original transfer, or the full amount of a transfer. Once we receive chargeback details from the card network, we process the chargeback by debiting the merchant’s Moov wallet.

Dispute notifications

You can receive notifications on disputes through the dispute.created and dispute.updated webhook events. Subscribing to that event will let you know the dispute was created, updated, and completed. The dispute.updated webhook will generate if there is a change to status or phase.

Alternatively, you can use the disputes list GET endpoint to pull a list of disputes on a recurring schedule.

Note that even if a transfer has a dispute, its overall transfer status will remain completed.

View dispute information

If a transfer has been disputed, you can see information about the dispute on the transfer object for the original transferID in question. A cardholder can dispute a charge for various reasons. The following response fields provide helpful information about a dispute and will allow merchants to compile the appropriate compelling evidence:

Field Description
networkReasonCode The card network’s category for the dispute. Codes may differ between card brands.
networkReasonDescription Card network categorization details of the dispute.
phase The current phase of a dispute.
status The current status of a dispute.

The following is an example of a dispute response:

  "amount": {
    "currency": "USD",
    "value": 1204
  "createdOn": "2023-08-24T14:15:22Z",
  "disputeID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
  "merchantAccountID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
  "networkReasonCode": "string",
  "networkReasonDescription": "string",
  "phase": "chargeback",
  "respondBy": "2023-08-24T14:15:22Z",
  "status": "response-needed",
  "transfer": {
    "transferID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43"


See the phase field in either of the dispute GET endpoint responses to see the current phase of a dispute. Disputes can have the following phases (note some phases currently only apply to specific card networks):

Status Description
pre-dispute Visa only. Moov supports Visa’s Rapid Dispute Resolution integration which helps merchants auto-resolve pre-disputes and avoids potential chargebacks.
inquiry American Express only. Preliminary phase before a formal chargeback is created.
chargeback Transfer is actively being disputed. Moov wallet is debited immediately.
unknown There was a processing error.

American Express may send an inquiry to a merchant to request more information regarding a chargeback. This is a preliminary phase before a formal chargeback is created - no funds are debited from the merchant’s Moov wallet. In this phase, merchants can either accept liability by refunding the transfer, or prevent a chargeback by providing sufficient information.

Dispute statuses

See the status field in either of the dispute GET endpoint responses to see the current status of a dispute. Disputes can have the following statuses:

Status Description
resolved No more action is required on these transactions.
response-needed Default response for all unresolved disputes. The merchant needs to communicate to Moov how they would like to proceed.
under-review Evidence has been submitted for a dispute and is being reviewed by the card network.
accepted The merchant has accepted liability for the dispute.
closed The issuer has reversed the chargeback, or evidence provided for the inquiry was sufficient.
won The evidence was compelling and the dispute was won. Funds have been credited back to the merchant wallet.
lost The evidence was not compelling and the dispute was lost.
expired The due date for a response to the chargeback or inquiry has passed.

Dispute information is also available in the Dashboard under Transfers > Disputes. See our Dashboard guide for more information.

Respond to disputes

If a merchant receives a chargeback, they can either accept liability or challenge the chargeback. Use the endpoints in the following sections to address specific stages of the dispute. If a merchant does not respond to a chargeback by the respondBy date, the chargeback expires and the merchant automatically accepts liability.

Once evidence is submitted, the merchant will need to wait for the card network’s final decision. If the evidence is sufficient, the dispute status will update to won and funds will be credited. If the evidence is insufficient, the dispute status will update to lost.

Response deadlines

Responses to disputes are due to Moov by the respondBy date and vary by card brand:

Card brand Dispute respondBy
Visa 14 calendar days
Mastercard 14 calendar days
Discover 14 calendar days
Amex 10 calendar days
It’s possible to receive an American Express chargeback without an inquiry phase. View dispute information for details about dispute phases.

Accept dispute

Accepting liability on a chargeback means the merchant will not contest the dispute and will accept the permanent return of the funds to the cardholder. This is final action and cannot be undone.

If the phase is chargeback and the status is response-needed, the dispute can be accepted using the dispute POST endpoint. If the dispute is successful, the status will update to accepted. When a dispute is accepted, there is no additional movement of funds. The funds debit when the chargeback is received.

If the phase is inquiry and the status is response-needed, the dispute can be accepted by refunding the transfer.

Challenge dispute

Challenging a chargeback requires gathering and submitting compelling evidence. Evidence can only be submitted once per dispute.

Upload evidence

Evidence must be uploaded before the respondBy due date. Evidence can only be uploaded if the phase is chargeback or inquiry and the status is response-needed.

Evidence must be tagged with one of the following evidence types listed below and adhere to file size and format guidelines.

Evidence type Description
receipt Proof of purchase notifying the customer about the charge.
proof-of-delivery Confirmation that the goods or services were delivered to the customer.
cancelation-policy Cancellation or refund policy as it was provided to the customer.
terms-of-service Terms of service policy as it was provided to the customer.
customer-communication Acknowledgement from cardholder withdrawing the dispute or email evidence that dispute was resolved.
cover-letter Summary of the challenge (Moov can provide guidelines or a template if requested).
generic-evidence Additional evidence that is outside the definition of the other evidence type categories.

There are two endpoints to upload evidence, depending on the evidence format. For example, you can upload a cover-letter as text and a receipt as a file.

After uploading all evidence, it must be submitted.

Update evidence

Evidence can only be updated if the dispute status is response-needed.

Use the dispute PATCH endpoint to update evidence.

Delete evidence

Use the dispute DEL endpoint to delete a specific piece of evidence.

Submit evidence

Evidence can only be submitted once per dispute – do not submit until everything is finalized. Evidence can only be submitted if the phase is chargeback or inquiry and the status is response-needed.

Evidence must be submitted before the respondBy due date and cannot be submitted with an empty evidence body. Once evidence is successfully submitted, the status will update to under-review.

Use the dispute POST endpoint to submit evidence.

Retrieve evidence

Use the dispute GET endpoints to retrieve evidence metadata for a specific dispute.

  • List all dispute evidence GET endpoint
  • Retrieve a specific piece of dispute evidence GET endpoint

The following is an example of retrieved evidence metadata:

    "evidenceID": "9b56817a-0f9f-4756-86a5-83cff8426d35",
    "disputeID": "a362c415-1ff3-445a-843a-2f6cf0e031ee",
    "createdOn": "2022-10-24T00:00:00Z",
    "evidenceType": "receipt",
    "filename": "receipt.jpg",
    "size": 467,
    "mimeType": "image/jpeg"
    "evidenceID": "4e677336-464c-4a0c-b125-65aa2422bad3",
    "disputeID": "a362c415-1ff3-445a-843a-2f6cf0e031ee",
    "createdOn": "2022-10-24T00:00:00Z",
    "evidenceType": "proof-of-delivery",
    "filename": "screenshot.jpg",
    "size": 723,
    "mimeType": "image/jpeg"

File size & format requirements

Moov requires supporting documents to fit within the following type, size, and naming specification parameters:

Type Size
PDF File size maximum is 2 MB
JPG/TIFF File size maximum is 1 MB

Naming specifications for all documents are as follows:

  • 16 or fewer alphanumeric characters
  • No special characters
  • Must not contain sensitive info (such as PANs)
Summary Beta