1. Guides
2. Money movement
3. Accept payments
4. Card acceptance

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:

The following is an example of a dispute response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "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"
  }
}

Phases

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):

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:

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.

Use the tabs below to view dispute flow diagrams based on phase.

A dispute with phase: chargeback will update to status: response-needed and the merchant is required to accept or deny liability. If the merchant denies liability, evidence will need to be submitted and the merchant will either win or lose the dispute. The dispute can also be closed by the issuer.

A dispute with phase: pre-dispute can be resolved through Visa’s Rapid Dispute Resolution, or closed by the issuer.

A dispute with phase: inquiry is in a preliminary chargeback phase and evidence can be submitted if the merchant denies liability. If the evidence submitted in the inquiry phase is deemed insufficient, the dispute will update to phase: chargeback. The liability and evidence process will start over and the merchant will either win or lose the dispute. The dispute can also be closed by the issuer.

Response deadlines

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

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.

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.

• File POST endpoint
• Text POST endpoint

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

[
  {
    "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:

Naming specifications for all documents are as follows:

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