> ## 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.

# Card Transaction Disputes

> Manage card disputes with the Synctera API: submit disputes, upload supporting documentation, and track status through the card network.

## Version 2 Rollout

<Info>
  This is the **Version 2 (V2)** Card Transaction Disputes guide. For the Version 1 flow, see [Card Transaction Disputes (V1)](/v1/docs/card-transaction-disputes).

  The planned rollout for Version 2 of Synctera's Dispute Management is as follows:

  * **Mastercard programs:** September 7 – October 7, 2026
    * Synctera will notify you of the exact date. Until then, follow the [V1](/v1/docs/card-transaction-disputes) flow.
  * **Visa and PULSE programs:** TBD
    * Keep following the [V1](/v1/docs/card-transaction-disputes) flow until further notice.

  **Key changes between V1 and V2:**

  * Reason codes have been streamlined (deprecated codes remain accepted for backward compatibility)
  * Comprehensive evidence gathering at dispute creation to strengthen the case — see [`evidence`](/v2/reference/createdispute#body-one-of-0-evidence) in the Create Dispute spec.
  * New lifecycle states, including more granular declined-dispute states: Withdrawn, Refunded, Expired, Rejected
  * Dispute document categories — some reason codes require specific categories on submission
</Info>

## Overview

In order to manage the card dispute process, the Synctera API provides support for the required tasks such as submitting a dispute, uploading supporting documentation, and tracking status through the card network. Synctera evaluates evidence and interacts with the card network on your behalf. As mentioned under [Transaction Disputes](/v2/docs/transaction-disputes), a [Dispute Case](/v2/docs/dispute-cases-fintechs) gets automatically created once a dispute is opened. The Dispute Case is used to track and reflect the dispute status through the Synctera Console.

## What Transactions Can Be Disputed?

* Only posted transactions can be disputed, and only if within 120 days from the settlement. A pending transaction cannot be disputed.
* A dispute cannot exceed the amount of the original transaction.
* For fraud disputes (`reason_code` = `UNAUTHORIZED_TRANSACTION`), the card must be terminated before the dispute can be created.

## Chargeback Dispute Lifecycle

The chargeback dispute lifecycle involves a series of **actions** between the issuer and acquirer, which continues until a decision is reached on who is financially responsible for the dispute. The dispute lifecycle is also described in [this article](/v2/docs/dispute-cases-fintechs).

Card disputes start in `EVIDENCE_GATHERING`. After evidence is submitted via `EVIDENCE_GATHERING.COMPLETE`, Synctera evaluates the case and files with the card network when appropriate. Subsequent lifecycle updates (chargeback, representment, outcomes, and similar) are applied automatically and surfaced via `DISPUTE.UPDATED` webhooks and GET responses.

#### 1. Chargeback

> Time frame within 120 days of settlement of the transaction.

A chargeback is filed when the transaction meets the conditions listed in the [reason codes](/v2/docs/card-transaction-disputes#reason-code) found below. This happens after `EVIDENCE_GATHERING.COMPLETE`, when Synctera determines a chargeback should be filed.

#### 2. Representment

> Time frame within 45 days of chargeback.

A representment occurs when the acquiring bank either has evidence to prove that the chargeback does not meet the requirements of the reason code or can provide information that addresses the original reason for the dispute.

#### 3. Pre-arbitration

> Time frame within 45 days of representment.

Pre-arbitration is the final chance for the issuing bank to provide further evidence that the cardholder should be refunded for their transaction.

#### 4. Arbitration

> Time frame within 75 days of pre-arbitration.

In the event that the issuer and acquirer cannot settle on an outcome of the financial responsibility of the transaction, the dispute can be raised to arbitration. Arbitration leaves the decision of who is financially responsible in the hands of third party arbitrators (the card network).

<Warning>
  Issuers and acquirers generally choose to avoid arbitration as it involves fees as high as \$500 or more per case in addition to any other fees associated with the dispute.
</Warning>

## Write-Offs

In cases where a transaction's value is lower than the cost of pursuing a dispute, it can be written off instead of filing with the card network. A write-off is submitted (`WRITE_OFF.SUBMITTED`) automatically or by an issuer, then accepted automatically (`WRITE_OFF.ACCEPTED`). Any provisional credit is reversed, a final credit is posted, and the dispute is closed.

### Automatic Write-Offs

Synctera can configure an automatic write-off threshold for your program. When a dispute is created and both of the following are true, Synctera routes it through the automatic write-off workflow instead of filing with the network:

* The disputed amount is less than or equal to the configured threshold
* The dispute is created no more than 120 days after the disputed transaction's effective date

Those disputes are created with `managed_by` = `AUTO_WRITE_OFF` and `network` = `NONE`. Synctera later submits a `WRITE_OFF` action automatically, moving the dispute to the `WRITE_OFF` lifecycle. No issuer network actions are available on automatic write-off disputes. Automatic write-off is enabled by default with a **\$25** threshold. Contact your Synctera representative to disable it or change the threshold for your program.

## Reason Code

When creating a dispute, the **Reason Code** is the most critical field in your request. It acts as the formal classification for the claim, signaling to the network exactly why the transaction is being challenged. Selecting the correct code ensures the case is evaluated under the proper network rules and significantly improves the chances of a successful resolution.

#### Selecting a Reason Code

To ensure your dispute meets all technical requirements, please refer to the supported codes in our documentation.

<Info>
  **View the Codes:** Click the link below and ensure the **Card Dispute** tab is selected in the **Body** parameters section to see the full list of codes and required documentation.
</Info>

* [View Available Reason Codes](/v2/reference/createdispute)

Some reason codes also require additional `evidence` on create, or a dispute document uploaded with a specific `category` before the case can be filed — see [Upload Supporting Documents](/v2/docs/transaction-disputes#2-upload-supporting-documents).

<Warning>
  Please ensure you are using **Active** codes. While some legacy codes are still accepted for backward compatibility, they are deprecated and will be automatically mapped to their modern equivalents by the API. Using the active code from the start ensures better tracking and transparency for your case.
</Warning>

## Card Dispute Lifecycle States

| Lifecycle                  | Description                                                                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| EVIDENCE\_GATHERING        | Initial state after a dispute is created. Supporting documents and evidence can be added before the case is filed with the network. |
| EVALUATION                 | Evidence gathering is complete and the case has been submitted for evaluation / network filing.                                     |
| MANUAL\_REVIEW             | The case requires manual review before proceeding.                                                                                  |
| WRITE\_OFF                 | The dispute has been written off and will not be filed with the card network.                                                       |
| CHARGEBACK                 | A chargeback has been filed with the card network. The acquiring bank may accept or file a re-presentment.                          |
| REPRESENTMENT              | The acquiring bank has filed a re-presentment. The case may proceed to pre-arbitration or resolve as won/lost.                      |
| PRE\_ARBITRATION           | A pre-arbitration case has been created with the network. The acquiring bank may rebut or the case may resolve.                     |
| PRE\_ARBITRATION\_RESPONSE | The acquiring bank has rebutted the pre-arbitration case. The case may escalate to arbitration or resolve.                          |
| ARBITRATION                | An arbitration case has been created with the card network. The network determines the outcome.                                     |
| WITHDRAWN                  | The dispute has been withdrawn at the request of the cardholder.                                                                    |
| REFUNDED                   | The cardholder has been refunded directly by the merchant through a separate channel.                                               |
| EXPIRED                    | The dispute has expired.                                                                                                            |
| REJECTED                   | The dispute has been rejected.                                                                                                      |

## Available Actions

Actions on a card dispute come from different actors. FinTech actions are available via the Disputes API. Issuer actions may be issued automatically or manually by a Synctera operator when a case needs review. Acquirer / network actions are applied automatically as the case progresses with the card network and appear in `action_history` via `DISPUTE.UPDATED` webhooks.

### Issuer Actions (FinTech)

Issuer actions available to FinTechs via the Disputes API.

| Lifecycle           | Action                        | Decision | Description                                                                                      |
| ------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| EVIDENCE\_GATHERING | `EVIDENCE_GATHERING.COMPLETE` | ONGOING  | Submit collected evidence and file the case with the network. Moves the dispute to `EVALUATION`. |
| \* (any open state) | `PROVISIONAL_CREDIT.CREATE`   | —        | Issue provisional credit as required by regulation or policy.                                    |
| \* (any open state) | `PROVISIONAL_CREDIT.REVERSE`  | —        | Reverse provisional credit as required by regulation or policy.                                  |

### Issuer Actions (Synctera)

Issuer actions that may be issued automatically or manually by a Synctera operator (for example in `MANUAL_REVIEW` after chargeback or representment review, or after a pre-arbitration rebuttal). These appear in `action_history` and trigger `DISPUTE.UPDATED` webhooks.

| Lifecycle                   | Action                         | Decision | Description                                                                                                 |
| --------------------------- | ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| \* (any open state)         | `PROVISIONAL_CREDIT.SUBMITTED` | —        | Issue provisional credit as required by regulation or policy.                                               |
| \* (any open state)         | `PROVISIONAL_CREDIT.REVERSED`  | —        | Reverse provisional credit as required by regulation or policy.                                             |
| EVALUATION / MANUAL\_REVIEW | `WRITE_OFF.SUBMITTED`          | ONGOING  | Case written off without (or instead of) pursuing a chargeback. Moves to `WRITE_OFF`.                       |
| EVALUATION / MANUAL\_REVIEW | `CHARGEBACK.SUBMITTED`         | ONGOING  | Chargeback filed with the card network. Moves to `CHARGEBACK`.                                              |
| EVALUATION / MANUAL\_REVIEW | `DISPUTE.REJECTED`             | NONE     | Case rejected.                                                                                              |
| CHARGEBACK                  | `DISPUTE.WITHDRAWN`            | NONE     | Case withdrawn while in chargeback.                                                                         |
| REPRESENTMENT               | `WRITE_OFF.SUBMITTED`          | ONGOING  | Case written off instead of continuing after representment; issuer accepts liability. Moves to `WRITE_OFF`. |
| REPRESENTMENT               | `DISPUTE.LOST`                 | LOST     | Cardholder accepts liability after representment; case lost.                                                |
| REPRESENTMENT               | `DISPUTE.REFUNDED`             | NONE     | Merchant credited the cardholder.                                                                           |
| REPRESENTMENT               | `DISPUTE.WITHDRAWN`            | NONE     | Case withdrawn while in representment.                                                                      |
| MANUAL\_REVIEW              | `PRE_ARBITRATION.SUBMITTED`    | ONGOING  | Pre-arbitration filed after representment review. Moves to `PRE_ARBITRATION`.                               |
| MANUAL\_REVIEW              | `DISPUTE.WITHDRAWN`            | NONE     | Case withdrawn at cardholder / Synctera request.                                                            |
| PRE\_ARBITRATION\_RESPONSE  | `WRITE_OFF.SUBMITTED`          | ONGOING  | Case written off instead of pursuing arbitration; issuer accepts liability. Moves to `WRITE_OFF`.           |
| PRE\_ARBITRATION\_RESPONSE  | `DISPUTE.LOST`                 | LOST     | Cardholder accepts liability after pre-arbitration rebuttal; case lost.                                     |
| PRE\_ARBITRATION\_RESPONSE  | `DISPUTE.REFUNDED`             | NONE     | Merchant credited the cardholder.                                                                           |
| PRE\_ARBITRATION\_RESPONSE  | `ARBITRATION.SUBMITTED`        | ONGOING  | Arbitration filed after pre-arbitration rebuttal. Moves to `ARBITRATION`.                                   |
| PRE\_ARBITRATION\_RESPONSE  | `DISPUTE.WITHDRAWN`            | NONE     | Case withdrawn after pre-arbitration response.                                                              |

### Acquirer / Network Actions

Applied automatically as the dispute progresses with the acquirer and card network. Action values below match `action_history` responses.

| Lifecycle                   | Action                      | Decision | Description                                                                        |
| --------------------------- | --------------------------- | -------- | ---------------------------------------------------------------------------------- |
| EVALUATION / MANUAL\_REVIEW | `DISPUTE.REFUNDED`          | NONE     | Merchant credited the cardholder outside the chargeback flow. Moves to `REFUNDED`. |
| EVALUATION / MANUAL\_REVIEW | `DISPUTE.EXPIRED`           | NONE     | Case expired.                                                                      |
| CHARGEBACK                  | `REPRESENTMENT.SUBMITTED`   | ONGOING  | Acquirer filed a re-presentment. Moves to `REPRESENTMENT`.                         |
| CHARGEBACK                  | `DISPUTE.WON`               | WON      | Chargeback accepted / case won (no representment).                                 |
| REPRESENTMENT               | `PRE_ARBITRATION.SUBMITTED` | ONGOING  | Pre-arbitration filed. Moves to `PRE_ARBITRATION`.                                 |
| PRE\_ARBITRATION            | `PRE_ARBITRATION.REBUTTED`  | ONGOING  | Acquirer rebutted pre-arbitration. Moves to `PRE_ARBITRATION_RESPONSE`.            |
| PRE\_ARBITRATION            | `DISPUTE.WON`               | WON      | Case won in pre-arbitration.                                                       |
| PRE\_ARBITRATION            | `DISPUTE.LOST`              | LOST     | Case lost in pre-arbitration.                                                      |
| ARBITRATION                 | `DISPUTE.WON`               | WON      | Case won in arbitration.                                                           |
| ARBITRATION                 | `DISPUTE.LOST`              | LOST     | Case lost in arbitration.                                                          |

## Provisional Credits

Provisional credits may be issued to the cardholder as a temporary measure while investigating the dispute. Whether or not a provisional credit is required, is determined by the applicable regulations.

The relevant regulations/timelines that apply can be derived from the transaction being disputed by identifying which type of card program the transaction belongs to.

| BIN Country | Customer Type | Card/BIN Type | Regulation   |
| ----------- | ------------- | ------------- | ------------ |
| US          | Consumer      | Debit         | Regulation E |
| US          | Consumer      | Credit        | Regulation Z |
| US          | Commercial    | Debit         | N/A          |
| US          | Commercial    | Credit        | N/A          |

### To Summarize:

* Regulation E (US) applies to consumer debit transactions - it mandates issuance of provisional credit to the customer account while the dispute is under investigation (within 10 business days for established customers, and within 20 business days for new customers)
* Regulation Z (US) applies to consumer credit transactions - it mandates that a transaction that is under dispute is not included in the outstanding/due balances, and is not included in the available credit balance
* These regulations also have strict timelines around customer notifications, which is ultimately the responsibility of the FinTech - for details, see [this article](/v2/docs/customer-support-and-complaints)
* There are no specific regulations around commercial transactions
* Card networks also have their own “zero liability” policies - cardholders won’t be held responsible for unauthorized charges made with their card or card information provided they promptly report the issue
* Note that although issuance of provisional credit may not be mandated by regulations, the FinTech may still decide to issue provisional credit

## Complex Business Flow Example

The following example walks through a card dispute: create → upload evidence → complete evidence gathering → chargeback filed → provisional credit → representment → dispute lost.

### 1. Dispute Created

A dispute is created on behalf of the cardholder. Disputes start in `EVIDENCE_GATHERING`. Include any required `evidence` fields for the chosen `reason_code`.

##### Request

<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": "Ordered item never arrived.",
    "reason_code": "GOODS_OR_SERVICES_NOT_PROVIDED",
    "evidence": {
      "merchant_contact": {
        "was_attempted": true,
        "date": "2024-05-20",
        "was_successful": false,
        "description": "Called merchant support; no tracking information provided."
      },
      "delivery": {
        "expected_date": "2024-05-15"
      }
    }
  }
  '
  ```
</CodeGroup>

##### Response

<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,
    "id": "018fc167-7672-729d-8d43-653518f3d939",
    "last_updated_time": "2024-05-28T22:48:24.279984Z",
    "managed_by": "GROUND_CONTROL",
    "memo": "Ordered item never arrived.",
    "network": "DECISIONLY",
    "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": "EVIDENCE_GATHERING",
        "state": "COMPLETE"
      }
    ],
    "lifecycle_state": "EVIDENCE_GATHERING",
    "network_eligibility": {
      "is_digital_wallet_token": false,
      "is_three_ds": false,
      "is_network_eligibility_overridden": false
    },
    "reason_code": "GOODS_OR_SERVICES_NOT_PROVIDED",
    "evidence": {
      "merchant_contact": {
        "was_attempted": true,
        "date": "2024-05-20",
        "was_successful": false,
        "description": "Called merchant support; no tracking information provided."
      },
      "delivery": {
        "expected_date": "2024-05-15"
      }
    },
    "acquirer_reference_number": "52405245204967729855476"
  }
  ```
</CodeGroup>

### 2. Upload Documents and Complete Evidence Gathering

Supporting documentation is uploaded to the dispute. Files must be JPEG, PNG, or PDF, max 4.5MB each, up to 10 documents. Optionally set `category` (for example `TRANSACTION_RECEIPT`, `MERCHANT_CORRESPONDENCE`, `OTHER`).

##### Request

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

##### Response

<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",
    "category": "OTHER",
    "tenant": "asbght_iujkio"
  }
  ```
</CodeGroup>

Complete evidence gathering to create and file the case with the network.

##### Request

<CodeGroup>
  ```bash Shell theme={"system"}
  curl \
  -X POST \
  $baseurl/v1/disputes/{$dispute_id}/actions \
  -H "Authorization: Bearer $apiKey" \
  --json '
  {
    "payment_rail": "CARD",
    "action": "EVIDENCE_GATHERING",
    "state": "COMPLETE"
  }
  '
  ```
</CodeGroup>

##### Response

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "id": "018fc16e-0355-7cea-bf80-b0eddd63d48a",
    "creation_time": "2024-05-28T22:58:30.396998Z",
    "tenant": "asbght_iujkio",
    "payment_rail": "CARD",
    "action": "EVIDENCE_GATHERING",
    "status": "COMPLETED",
    "external_reference_id": "018fc167-7672-729d-8d43-653518f3d939"
  }
  ```
</CodeGroup>

#### Dispute State

The dispute moves to `EVALUATION`. Synctera then evaluates and may file a chargeback (or write-off / request review). Further network steps arrive as webhook-driven action history updates.

<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",
        "category": "OTHER",
        "tenant": "asbght_iujkio"
      }
    ],
    "disputed_amount": 500,
    "id": "018fc167-7672-729d-8d43-653518f3d939",
    "last_action_by": "INITIATOR",
    "last_updated_time": "2024-05-28T22:58:30.396998Z",
    "managed_by": "GROUND_CONTROL",
    "memo": "Ordered item never arrived.",
    "network": "DECISIONLY",
    "payment_rail": "CARD",
    "status": "OPEN",
    "tenant": "asbght_iujkio",
    "transaction_id": "018fc168-3ce3-7839-8cd3-a653bc4aa9bc",
    "action_history": [
      {
        "id": "018fc16e-0355-7cea-bf80-b0eddd63d48a",
        "creation_time": "2024-05-28T22:58:30.396998Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "EVIDENCE_GATHERING",
        "status": "COMPLETED",
        "external_reference_id": "018fc167-7672-729d-8d43-653518f3d939"
      }
    ],
    "available_actions": [
      {
        "action": "PROVISIONAL_CREDIT",
        "state": "CREATE"
      }
    ],
    "lifecycle_state": "EVALUATION",
    "network_eligibility": {
      "is_digital_wallet_token": false,
      "is_three_ds": false,
      "is_network_eligibility_overridden": false
    },
    "reason_code": "GOODS_OR_SERVICES_NOT_PROVIDED",
    "evidence": {
      "merchant_contact": {
        "was_attempted": true,
        "date": "2024-05-20",
        "was_successful": false,
        "description": "Called merchant support; no tracking information provided."
      },
      "delivery": {
        "expected_date": "2024-05-15"
      }
    },
    "acquirer_reference_number": "52405245204967729855476"
  }
  ```
</CodeGroup>

### 3. Chargeback Submitted

After evaluation, Synctera files a chargeback with the card network. This appears as a `DISPUTE.UPDATED` webhook with `CHARGEBACK.SUBMITTED` in `action_history`. The dispute moves to `CHARGEBACK`.

#### Dispute State

<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",
        "category": "OTHER",
        "tenant": "asbght_iujkio"
      }
    ],
    "disputed_amount": 500,
    "id": "018fc167-7672-729d-8d43-653518f3d939",
    "last_action_by": "NETWORK",
    "last_updated_time": "2024-05-29T09:00:00.000000Z",
    "managed_by": "GROUND_CONTROL",
    "memo": "Ordered item never arrived.",
    "network": "DECISIONLY",
    "payment_rail": "CARD",
    "status": "OPEN",
    "tenant": "asbght_iujkio",
    "transaction_id": "018fc168-3ce3-7839-8cd3-a653bc4aa9bc",
    "action_history": [
      {
        "id": "018fc16e-0355-7cea-bf80-b0eddd63d48a",
        "creation_time": "2024-05-28T22:58:30.396998Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "EVIDENCE_GATHERING",
        "status": "COMPLETED",
        "external_reference_id": "018fc167-7672-729d-8d43-653518f3d939"
      },
      {
        "id": "018fcb2e-1111-7cea-bf80-b0eddd63d48a",
        "creation_time": "2024-05-29T09:00:00.000000Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "CHARGEBACK",
        "status": "SUBMITTED"
      }
    ],
    "available_actions": [
      {
        "action": "PROVISIONAL_CREDIT",
        "state": "CREATE"
      }
    ],
    "lifecycle_state": "CHARGEBACK",
    "network_eligibility": {
      "is_digital_wallet_token": false,
      "is_three_ds": false,
      "is_network_eligibility_overridden": false
    },
    "reason_code": "GOODS_OR_SERVICES_NOT_PROVIDED",
    "evidence": {
      "merchant_contact": {
        "was_attempted": true,
        "date": "2024-05-20",
        "was_successful": false,
        "description": "Called merchant support; no tracking information provided."
      },
      "delivery": {
        "expected_date": "2024-05-15"
      }
    },
    "acquirer_reference_number": "52405245204967729855476"
  }
  ```
</CodeGroup>

### 4. Post Provisional Credit

A provisional credit may be issued after the chargeback has been filed.

##### Request

<CodeGroup>
  ```bash Shell theme={"system"}
  curl \
  -X POST \
  $baseurl/v1/disputes/{$dispute_id}/actions \
  -H "Authorization: Bearer $apiKey" \
  --json '
  {
    "payment_rail": "CARD",
    "action": "PROVISIONAL_CREDIT",
    "state": "CREATE"
  }
  '
  ```
</CodeGroup>

##### Response

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "id": "018fcb2f-50f4-7514-a82d-e6143f57f25f",
    "creation_time": "2024-05-29T10:00:00.000000Z",
    "tenant": "asbght_iujkio",
    "payment_rail": "CARD",
    "action": "PROVISIONAL_CREDIT",
    "status": "SUBMITTED"
  }
  ```
</CodeGroup>

#### Dispute State

<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": "PROVISIONAL",
    "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",
        "category": "OTHER",
        "tenant": "asbght_iujkio"
      }
    ],
    "disputed_amount": 500,
    "id": "018fc167-7672-729d-8d43-653518f3d939",
    "last_action_by": "INITIATOR",
    "last_updated_time": "2024-05-29T10:00:00.000000Z",
    "managed_by": "GROUND_CONTROL",
    "memo": "Ordered item never arrived.",
    "network": "DECISIONLY",
    "payment_rail": "CARD",
    "status": "OPEN",
    "tenant": "asbght_iujkio",
    "transaction_id": "018fc168-3ce3-7839-8cd3-a653bc4aa9bc",
    "action_history": [
      {
        "id": "018fc16e-0355-7cea-bf80-b0eddd63d48a",
        "creation_time": "2024-05-28T22:58:30.396998Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "EVIDENCE_GATHERING",
        "status": "COMPLETED",
        "external_reference_id": "018fc167-7672-729d-8d43-653518f3d939"
      },
      {
        "id": "018fcb2e-1111-7cea-bf80-b0eddd63d48a",
        "creation_time": "2024-05-29T09:00:00.000000Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "CHARGEBACK",
        "status": "SUBMITTED"
      },
      {
        "id": "018fcb2f-50f4-7514-a82d-e6143f57f25f",
        "creation_time": "2024-05-29T10:00:00.000000Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "PROVISIONAL_CREDIT",
        "status": "SUBMITTED"
      }
    ],
    "available_actions": [
      {
        "action": "PROVISIONAL_CREDIT",
        "state": "REVERSE"
      }
    ],
    "lifecycle_state": "CHARGEBACK",
    "network_eligibility": {
      "is_digital_wallet_token": false,
      "is_three_ds": false,
      "is_network_eligibility_overridden": false
    },
    "reason_code": "GOODS_OR_SERVICES_NOT_PROVIDED",
    "evidence": {
      "merchant_contact": {
        "was_attempted": true,
        "date": "2024-05-20",
        "was_successful": false,
        "description": "Called merchant support; no tracking information provided."
      },
      "delivery": {
        "expected_date": "2024-05-15"
      }
    },
    "acquirer_reference_number": "52405245204967729855476"
  }
  ```
</CodeGroup>

### 5. Webhook Received for Representment

#### Dispute State

A representment from the acquirer is reflected on the dispute via `DISPUTE.UPDATED`, including any supporting documentation from the network.

<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": "PROVISIONAL",
    "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",
        "category": "OTHER",
        "tenant": "asbght_iujkio"
      },
      {
        "creation_time": "2024-05-30T20:32:00.000000Z",
        "dispute_id": "018fc167-7672-729d-8d43-653518f3d939",
        "file_name": "representment.pdf",
        "id": "018fcb30-90a1-7221-9160-28917c2cfc2d",
        "tenant": "asbght_iujkio"
      }
    ],
    "disputed_amount": 500,
    "id": "018fc167-7672-729d-8d43-653518f3d939",
    "last_action_by": "NETWORK",
    "last_updated_time": "2024-05-30T20:32:03.787519Z",
    "managed_by": "GROUND_CONTROL",
    "memo": "Ordered item never arrived.",
    "network": "DECISIONLY",
    "payment_rail": "CARD",
    "status": "OPEN",
    "tenant": "asbght_iujkio",
    "transaction_id": "018fc168-3ce3-7839-8cd3-a653bc4aa9bc",
    "action_history": [
      {
        "id": "018fc16e-0355-7cea-bf80-b0eddd63d48a",
        "creation_time": "2024-05-28T22:58:30.396998Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "EVIDENCE_GATHERING",
        "status": "COMPLETED",
        "external_reference_id": "018fc167-7672-729d-8d43-653518f3d939"
      },
      {
        "id": "018fcb2e-1111-7cea-bf80-b0eddd63d48a",
        "creation_time": "2024-05-29T09:00:00.000000Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "CHARGEBACK",
        "status": "SUBMITTED"
      },
      {
        "id": "018fcb2f-50f4-7514-a82d-e6143f57f25f",
        "creation_time": "2024-05-29T10:00:00.000000Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "PROVISIONAL_CREDIT",
        "status": "SUBMITTED"
      },
      {
        "id": "018e62f5-8141-708f-a924-c706d82876a5",
        "creation_time": "2024-05-30T20:32:03.787519Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "REPRESENTMENT",
        "status": "SUBMITTED",
        "supporting_doc_id": "018fcb30-90a1-7221-9160-28917c2cfc2d",
        "message": "Merchant provided proof of delivery"
      }
    ],
    "available_actions": [
      {
        "action": "PROVISIONAL_CREDIT",
        "state": "REVERSE"
      }
    ],
    "lifecycle_state": "REPRESENTMENT",
    "network_eligibility": {
      "is_digital_wallet_token": false,
      "is_three_ds": false,
      "is_network_eligibility_overridden": false
    },
    "reason_code": "GOODS_OR_SERVICES_NOT_PROVIDED",
    "evidence": {
      "merchant_contact": {
        "was_attempted": true,
        "date": "2024-05-20",
        "was_successful": false,
        "description": "Called merchant support; no tracking information provided."
      },
      "delivery": {
        "expected_date": "2024-05-15"
      }
    },
    "acquirer_reference_number": "52405245204967729855476"
  }
  ```
</CodeGroup>

### 6. Dispute Lost

The issuer records that the cardholder accepts liability after representment (`DISPUTE.LOST`).

##### Request

<CodeGroup>
  ```bash Shell theme={"system"}
  curl \
  -X POST \
  $baseurl/v1/disputes/{$dispute_id}/actions \
  -H "Authorization: Bearer $apiKey" \
  --json '
  {
    "payment_rail": "CARD",
    "action": "DISPUTE",
    "state": "LOST"
  }
  '
  ```
</CodeGroup>

#### Dispute State

The dispute now reflects the final decision. Any outstanding provisional credit is reversed on a delay (not immediately).

<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": "PROVISIONAL",
    "currency": "USD",
    "customer_id": "018fc166-b34b-7211-aa8d-1ca6c6b7b1e8",
    "date_customer_reported": "2024-05-28T12:25:00Z",
    "decision": "LOST",
    "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",
        "category": "OTHER",
        "tenant": "asbght_iujkio"
      },
      {
        "creation_time": "2024-05-30T20:32:00.000000Z",
        "dispute_id": "018fc167-7672-729d-8d43-653518f3d939",
        "file_name": "representment.pdf",
        "id": "018fcb30-90a1-7221-9160-28917c2cfc2d",
        "tenant": "asbght_iujkio"
      }
    ],
    "disputed_amount": 500,
    "id": "018fc167-7672-729d-8d43-653518f3d939",
    "last_action_by": "INITIATOR",
    "last_updated_time": "2024-05-31T20:32:03.787519Z",
    "managed_by": "GROUND_CONTROL",
    "memo": "Ordered item never arrived.",
    "network": "DECISIONLY",
    "payment_rail": "CARD",
    "status": "OPEN",
    "tenant": "asbght_iujkio",
    "timestamp_final_decision": "2024-05-31T20:32:03.787519Z",
    "transaction_id": "018fc168-3ce3-7839-8cd3-a653bc4aa9bc",
    "action_history": [
      {
        "id": "018fc16e-0355-7cea-bf80-b0eddd63d48a",
        "creation_time": "2024-05-28T22:58:30.396998Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "EVIDENCE_GATHERING",
        "status": "COMPLETED",
        "external_reference_id": "018fc167-7672-729d-8d43-653518f3d939"
      },
      {
        "id": "018fcb2e-1111-7cea-bf80-b0eddd63d48a",
        "creation_time": "2024-05-29T09:00:00.000000Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "CHARGEBACK",
        "status": "SUBMITTED"
      },
      {
        "id": "018fcb2f-50f4-7514-a82d-e6143f57f25f",
        "creation_time": "2024-05-29T10:00:00.000000Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "PROVISIONAL_CREDIT",
        "status": "SUBMITTED"
      },
      {
        "id": "018e62f5-8141-708f-a924-c706d82876a5",
        "creation_time": "2024-05-30T20:32:03.787519Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "REPRESENTMENT",
        "status": "SUBMITTED",
        "supporting_doc_id": "018fcb30-90a1-7221-9160-28917c2cfc2d",
        "message": "Merchant provided proof of delivery"
      },
      {
        "id": "018e62fa-4e7a-7814-9634-e130c66f6444",
        "creation_time": "2024-05-31T20:32:03.787519Z",
        "tenant": "asbght_iujkio",
        "payment_rail": "CARD",
        "action": "DISPUTE",
        "status": "LOST"
      }
    ],
    "available_actions": [
      {
        "action": "PROVISIONAL_CREDIT",
        "state": "REVERSE"
      }
    ],
    "lifecycle_state": "REPRESENTMENT",
    "network_eligibility": {
      "is_digital_wallet_token": false,
      "is_three_ds": false,
      "is_network_eligibility_overridden": false
    },
    "reason_code": "GOODS_OR_SERVICES_NOT_PROVIDED",
    "evidence": {
      "merchant_contact": {
        "was_attempted": true,
        "date": "2024-05-20",
        "was_successful": false,
        "description": "Called merchant support; no tracking information provided."
      },
      "delivery": {
        "expected_date": "2024-05-15"
      }
    },
    "acquirer_reference_number": "52405245204967729855476"
  }
  ```
</CodeGroup>

### 7. Close Dispute

After the provisional credit has been reversed (`credit_status` = `NONE`), close the dispute.

##### Request

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

## Simulating Network Dispute Actions

<Warning>
  **Sandbox Environment Only**

  Simulations are intended for use only in the testing environment to simulate a network action on a dispute. For dispute creation and issuer actions, follow the steps listed in the [Transaction Disputes API Guide](/v2/docs/transaction-disputes).
</Warning>

In production, acquirer / network actions are applied automatically as the case progresses with the card network. In sandbox, use simulations to advance those same steps without waiting on a live network response.

Network dispute simulations must follow the logical order of the dispute lifecycle — for example, after a chargeback is submitted you can simulate a representment. For a complete list of network actions, see [Acquirer / Network Actions](/v2/docs/card-transaction-disputes#acquirer--network-actions).

To progress a dispute to the next lifecycle and simulate a network response, use [`POST /v1/disputes/simulations/{$dispute_id}/actions`](/v2/reference/simulatedisputeaction). Request bodies use `state` (for example `CREATE`); matching entries in `action_history` use `status` (for example `SUBMITTED`).

<CodeGroup>
  ```bash Shell theme={"system"}
  curl \
  -X POST \
  $baseurl/v1/disputes/simulations/{$dispute_id}/actions \
  -H "Authorization: Bearer $apiKey" \
  --json '
  {
    "payment_rail": "CARD",
    "action": "REPRESENTMENT",
    "state": "CREATE",
    "message": "Merchant provided proof of delivery"
  }
  '
  ```
</CodeGroup>