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

This is the Version 2 (V2) Card Transaction Disputes guide. For the Version 1 flow, see Card Transaction Disputes (V1).

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 flow.
• Visa and PULSE programs: TBD
  • Keep following the V1 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 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

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, a Dispute Case 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.

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

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.

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.

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.

• View Available Reason Codes

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.

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.

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
• 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

Shell

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

Response

JSON

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

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

Shell

curl \
-X POST \
$baseurl/v1/disputes/{$dispute_id}/documents \
-H "Authorization: Bearer $apiKey" \
-F file=@file.pdf \
-F category=OTHER

Response

JSON

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

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

Request

Shell

curl \
-X POST \
$baseurl/v1/disputes/{$dispute_id}/actions \
-H "Authorization: Bearer $apiKey" \
--json '
{
  "payment_rail": "CARD",
  "action": "EVIDENCE_GATHERING",
  "state": "COMPLETE"
}
'

Response

JSON

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

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.

JSON

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

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

JSON

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

4. Post Provisional Credit

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

Request

Shell

curl \
-X POST \
$baseurl/v1/disputes/{$dispute_id}/actions \
-H "Authorization: Bearer $apiKey" \
--json '
{
  "payment_rail": "CARD",
  "action": "PROVISIONAL_CREDIT",
  "state": "CREATE"
}
'

Response

JSON

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

Dispute State

JSON

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

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.

JSON

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

6. Dispute Lost

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

Request

Shell

curl \
-X POST \
$baseurl/v1/disputes/{$dispute_id}/actions \
-H "Authorization: Bearer $apiKey" \
--json '
{
  "payment_rail": "CARD",
  "action": "DISPUTE",
  "state": "LOST"
}
'

Dispute State

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

JSON

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

7. Close Dispute

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

Request

Shell

curl \
-X PATCH \
$baseurl/v1/disputes/{$dispute_id} \
-H "Authorization: Bearer $apiKey" \
--json '
{
  "status": "CLOSED"
}
'

Simulating Network Dispute Actions

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.

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.

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

Shell

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