> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synctera.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction Disputes

> Cardholders can dispute transactions made on their card or their account for many reasons ranging from not recognizing the transaction to fraudulent transactions by an unauthorized user.

## Overview

Disputing a transaction involves a series of actions between the two parties involved in a dispute, where supporting documentation is exchanged until a decision is reached on who is financially responsible. To begin the dispute process a dispute is opened on a transaction. The dispute can be opened through the Synctera Console or the Disputes API, which is described below. When the dispute is opened, a Dispute Case is automatically created. The Dispute and the Dispute case are used to track the dispute details, lifecycle and events that occur during the investigation into the dispute. The Dispute Case and the Dispute Lifecycle are described in this [article](/docs/dispute-cases-fintechs).

Through both the Dispute Case in the Synctera Console, and the Disputes API, the user is guided through the Dispute Flow. Depending on the payment rail of the original transaction that is being disputed, a list of available actions will be returned to process the next step of the dispute. Once an action is created against a dispute, subsequent actions will be made available to the opposing party.

## Webhook Events

To monitor transaction disputes, webhooks are triggered anytime one of the following events occurs:

| Webhook           | Description                           |
| ----------------- | ------------------------------------- |
| `DISPUTE.CREATED` | A new dispute has been created.       |
| `DISPUTE.UPDATED` | An existing dispute has been updated. |

To subscribe to the dispute webhooks refer to the [Webhooks Guide](/docs/webhooks-guide).

## Disputing a Transaction

The following steps will walk you through the process of disputing a transaction.

Refer to the links below for specific details on supported payment rails:

<CardGroup>
  <Card title="Card Transaction Disputes" href="/v1/docs/card-transaction-disputes" icon="angle-right" iconType="solid" horizontal={true} />
</CardGroup>

### 1. Create a Dispute

To create a dispute, use [POST /v1/disputes](/v1/reference/createdispute).

<CodeGroup>
  ```bash Shell theme={"system"}
  curl \
  -X POST \
  $baseurl/v1/disputes \
  -H "Authorization: Bearer $apiKey" \
  --json '
  {
      "payment_rail": "CARD",
      "transaction_id": {TRANSACTION_ID},
      "disputed_amount": 500,
      "date_customer_reported": "2024-05-28T12:25:00.000Z",
      "memo": "Some details about the reason for creating the dispute.",
      "reason_code": "TRANSACTION_NOT_RECOGNIZED",
  }
  '
  ```
</CodeGroup>

This will return a response with the created dispute.

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "account_id": "018fc166-8874-7f3c-943a-178ad1c31903",
    "applicable_regulation": "REGULATION_Z",
    "creation_time": "2024-05-28T22:48:24.279984Z",
    "credit_status": "NONE",
    "currency": "USD",
    "customer_id": "018fc166-b34b-7211-aa8d-1ca6c6b7b1e8",
    "date_customer_reported": "2024-05-28T12:25:00Z",
    "decision": "ONGOING",
    "dispute_documents": [],
    "disputed_amount": 500,
    "external_reference_id": "030964295796",
    "id": "018fc167-7672-729d-8d43-653518f3d939",
    "last_updated_time": "2024-05-28T22:48:24.279984Z",
    "memo": "Some details about the reason for creating the dispute.",
    "network": "MASTERCARD",
    "payment_rail": "CARD",
    "status": "OPEN",
    "tenant": "asbght_iujkio",
    "transaction_id": "018fc168-3ce3-7839-8cd3-a653bc4aa9bc",
    "action_history": [],
    "available_actions": [
      {
        "action": "PROVISIONAL_CREDIT",
        "state": "CREATE"
      },
      {
        "action": "WRITE_OFF",
        "state": "CREATE"
      },
      {
        "action": "CHARGEBACK",
        "state": "CREATE",
        "timestamp_valid_to": "2024-08-23T00:00:00Z"
      }
    ],
    "lifecycle_state": "PENDING_ACTION",
    "network_eligibility": {
      "is_digital_wallet_token": false,
      "is_three_ds": false
    },
    "reason_code": "DUPLICATE_TRANSACTION"
  }
  ```
</CodeGroup>

Note the returned `id` attribute and the list of `available_actions`.

### 2. Upload Supporting Documents

To add supporting documentation to the dispute, use [POST /v1/disputes/\{dispute\_id}/documents](/v1/reference/adddisputedocument)

<CodeGroup>
  ```bash Shell theme={"system"}
  curl \
  -X POST
  $baseurl/v1/disputes/{$dispute_id}/documents \
  -H "Authorization: Bearer $apiKey" \
  -F file=@file.pdf
  ```
</CodeGroup>

This will return a response with the created document.

<CodeGroup>
  ```json JSON theme={"system"}
  {
      "creation_time": "2024-05-28T22:56:12.921781Z",
      "dispute_id": "018fc167-7672-729d-8d43-653518f3d939",
      "file_name": "file.pdf",
      "id": "018fc16b-bd41-70bc-89fe-f4330867ba73",
      "tenant": "asbght_iujkio"
  }
  ```
</CodeGroup>

Note the returned `id` attribute as it will be used to include the document in subsequent dispute actions.

### 3. Create a Dispute Action

Select the action you wish to create from the list of `available_actions` on the dispute.

To create the action, use [POST /v1/disputes/\{\$dispute\_id}/actions](/v1/reference/createaction)

<CodeGroup>
  ```bash Shell theme={"system"}
  curl \
  -X POST \
  $baseurl/v1/disputes/{$dispute_id}/actions \
  -H "Authorization: Bearer $apiKey" \
  --json '
  {
    "payment_rail": "CARD",
    "action": "CHARGEBACK",
    "state": "CREATE",
    "supporting_doc_id": "018fc16b-bd41-70bc-89fe-f4330867ba73",
    "message": "Some things about chargeback"
  }
  '
  ```
</CodeGroup>

This will return a response with the created action.

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "action": "CHARGEBACK",
    "creation_time": "2024-05-28T22:58:30.396998Z",
    "external_reference_id": "806796815213",
    "id": "018fc16e-0355-7cea-bf80-b0eddd63d48a",
    "message": "test chargeback",
    "payment_rail": "CARD",
    "reason_code": "DUPLICATE_TRANSACTION",
    "status": "SUBMITTED",
    "supporting_doc_id": "018fc16b-bd41-70bc-89fe-f4330867ba73",
    "tenant": "asbght_iujkio"
  }
  ```
</CodeGroup>

### 4. Monitor for Network Updates

When a response is received from the network a `DISPUTE.UPDATE` webhook is triggered and the dispute will contain the updated action history. Depending on the action received a decision on the dispute may be reached or further actions may be available.

In the event that the dispute decision is still `ONGOING` the update received from the network should contain further evidence for review.

An example `DISPUTE.UPDATE` for a re-presentment will contain additional dispute info as follows:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "account_id": "018fc166-8874-7f3c-943a-178ad1c31903",
    "applicable_regulation": "REGULATION_Z",
    "creation_time": "2024-05-28T22:48:24.279984Z",
    "credit_status": "NONE",
    "currency": "USD",
    "customer_id": "018fc166-b34b-7211-aa8d-1ca6c6b7b1e8",
    "date_customer_reported": "2024-05-28T12:25:00Z",
    "decision": "ONGOING",
    "dispute_documents": [
      {
        "creation_time": "2024-05-28T22:56:12.921781Z",
        "dispute_id": "018fc167-7672-729d-8d43-653518f3d939",
        "file_name": "file.pdf",
        "id": "018fc16b-bd41-70bc-89fe-f4330867ba73",
        "tenant": "asbght_iujkio"
      },
      {
        "creation_time": "2024-05-29T22:56:12.921781Z",
        "dispute_id": "018fc167-7672-729d-8d43-653518f3d939",
        "file_name": "file.pdf",
        "id": "018fc171-378d-75e0-b310-0e94c93da833",
        "tenant": "asbght_iujkio"
      }
    ],
    "disputed_amount": 500,
    "external_reference_id": "030964295796",
    "id": "018fc167-7672-729d-8d43-653518f3d939",
    "last_updated_time": "2024-05-28T22:48:24.279984Z",
    "memo": "Some details about the reason for creating the dispute.",
    "network": "MASTERCARD",
    "payment_rail": "CARD",
    "status": "OPEN",
    "tenant": "asbght_iujkio",
    "transaction_id": "018fc168-3ce3-7839-8cd3-a653bc4aa9bc",
    "action_history": [
      {
        "action": "CHARGEBACK",
        "creation_time": "2024-05-28T22:58:30.396998Z",
        "external_reference_id": "806796815213",
        "id": "018fc16e-0355-7cea-bf80-b0eddd63d48a",
        "message": "test chargeback",
        "payment_rail": "CARD",
        "reason_code": "DUPLICATE_TRANSACTION",
        "status": "SUBMITTED",
        "supporting_doc_id": "018fc16b-bd41-70bc-89fe-f4330867ba73",
        "tenant": "asbght_iujkio"
      },
      {
        "action": "REPRESENTMENT",
        "creation_time": "2024-05-29T22:58:30.396998Z",
        "external_reference_id": "806796815213",
        "id": "018fc171-c5bd-76ce-aab2-4515eac1c2aa",
        "message": "test representment",
        "payment_rail": "CARD",
        "status": "SUBMITTED",
        "supporting_doc_id": "018fc171-378d-75e0-b310-0e94c93da833",
        "tenant": "asbght_iujkio"
      }
    ],
    "available_actions": [
      {
        "action": "PROVISIONAL_CREDIT",
        "state": "CREATE"
      },
      {
        "action": "REPRESENTMENT",
        "state": "ACCEPT"
      }
    ],
    "lifecycle_state": "REPRESENTMENT",
    "network_eligibility": {
      "is_digital_wallet_token": false,
      "is_three_ds": false
    },
    "reason_code": "DUPLICATE_TRANSACTION"
  }
  ```
</CodeGroup>

Note the `supporting_doc_id` of the new action as it will be used to retrieve the new document contents for review.

### 5. Review Additional Supporting Documents

To retrieve supporting documentation from the dispute, use [GET /v1/disputes/documents/\{document\_id}/contents](/v1/reference/getdisputedocumentcontents)

<CodeGroup>
  ```bash Shell theme={"system"}
  curl \
  -X GET
  $baseurl/v1/disputes/{$document_id}/contents \
  -H "Authorization: Bearer $apiKey" \
  -o file.pdf
  ```
</CodeGroup>

### 6. File Additional Actions as Needed

If the dispute has reached a final decision `WON` or `LOST` no further action is required. If the dispute decision is `ONGOING` additional actions will be available on the dispute and a decision on how to continue the dispute is needed based on review of the additional supporting documentation. Actions can continue to be taken to progress the dispute through its lifecycle until a final decision is reached.

### 7. Close Dispute

To close the dispute, use [PATCH /v1/disputes/\{dispute\_id}](/v1/reference/updatedispute)

<CodeGroup>
  ```bash Shell theme={"system"}
  curl \
  -X PATCH
  $baseurl/v1/disputes/{$document_id}/contents \
  -H "Authorization: Bearer $apiKey" \
  --json '
  {
    "status": "CLOSED"
  }
  '
  ```
</CodeGroup>