Card Transaction Disputes

Overview

In order to manage the card dispute process, the Synctera API provides support for the required tasks such as submitting a dispute to the network, uploading supporting documentation and retrieving information from the card network. 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.

Network Eligibility

Even if a transaction can be disputed, it may not be eligible for a chargeback with the network. In order to be eligible for a chargeback, a transaction must not be processed with a digital wallet token or authenticated using 3DS. The API response will return an object with any network eligibility restrictions:

  "network_eligibility": {
    "is_digital_wallet_token": false,
    "is_three_ds": false
  }

Disputes which are not network eligible may be chosen to be written off. Refer to Write Offs below.

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.

1. Chargeback

Time frame within 120 days of settlement of the transaction.

A chargeback is submitted by the issuer when the transaction meets the conditions listed in the reason codes found below.

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.

Some chargeback reason codes allow for an arbitration case to be filed without the need for pre-arbitration. This will be reflected in the list of available actions on the dispute.

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.

Compliance Lifecycle

In the event that either the issuer or acquirer has violated network rules or the reason for dispute does not apply to one of the available reason codes a compliance case can be raised with the network.

A compliance case can be filed by the issuer or acquirer - the cardholder is not involved in the decision. A compliance case can be filed against a transaction by either party any time prior to the start of the chargeback dispute lifecycle. In the event that a chargeback dispute lifecycle has completed and either party believes that the transaction is valid for compliance, the transaction can be sent to the network in a subsequent compliance case.

Pre-compliance

Time frame within 90 days of settlement of the transaction.

Pre-compliance is the first step in the compliance case lifecycle and gives both parties the opportunity to settle the dispute before raising to compliance.

Compliance

Time frame within 120 days of settlement of the transaction.

In the event that the issuer and acquirer cannot settle the case during pre-compliance, a compliance case may be created. The card network will determine who is financially responsible.

Write Offs

In cases where a transaction's value is lower than the cost of pursuing a dispute or the transaction doesn't meet eligibility requirements of the network, it can be written off. Once a write off has been created, a provisional credit can be issued if required and no further action is needed.

Dispute Networks

📘
Available Networks
From November 2024, most Mastercard transactions will be processed directly through Mastercard (network = MASTERCARD). Other transactions, including Visa transactions, will be processed through Marqeta (network = MARQETA).

When a dispute is created the processing network will be determined and returned in the API responses network field. Depending on the processing network available actions may be limited.

Network	Description
MASTERCARD	Mastercard dual message transactions can be processed directly with the Mastercard network. All actions will be available. Dual message transactions are transactions that are processed over the credit networks, and have an authorization and a clearing component.
MARQETA	All other transactions will be processed through Marqeta - Marqeta handles the direct communication with the networks’ dispute management systems. A limited action set will be available for write off and provisional credit actions. In the event a chargeback is being pursued, further action will need to be taken by Synctera Ops (Ground Control). The dispute will continue to be updated with action history as available. Updates will trigger a webhook event and be available through all GET operations.

Network

Description

MASTERCARD

Mastercard dual message transactions can be processed directly with the Mastercard network. All actions will be available. Dual message transactions are transactions that are processed over the credit networks, and have an authorization and a clearing component.

MARQETA

All other transactions will be processed through Marqeta - Marqeta handles the direct communication with the networks’ dispute management systems. A limited action set will be available for write off and provisional credit actions. In the event a chargeback is being pursued, further action will need to be taken by Synctera Ops (Ground Control). The dispute will continue to be updated with action history as available. Updates will trigger a webhook event and be available through all GET operations.

Reason Code

Reason Code	Description
ATM_CASH_DISPUTE	Some or all funds debited from the cardholder's account as the result of an ATM withdrawal were not dispensed.
CARD_LOST_STOLEN_NEVER_RECEIVED	The cardholder did not authorize the transaction and the card is no longer, or had never been, in the possession of the cardholder.
CHIP_LIABILITY_SHIFT	A fraudulent transaction resulted from the use of a counterfeit card at a non-hybrid terminal for a validly issued emv card.
COUNTERFEIT_GOODS	The cardholder claims that the goods were purported to be genuine, but were counterfeit.
CREDIT_NOT_RECEIVED	The cardholder's account was not credited for a refund from a merchant or was inaccurately debited instead of credited.
DEFECTIVE_GOODS_OR_SERVICES	Goods or services were either not as described or defective, including shipped merchandise was received damaged or not suitable for its intended purpose as well as the merchant didn't honor the terms and conditions of a contract.
DISPUTE_OF_RECURRING_TRANSACTION	The cardholder notified the merchant to cancel the recurring transaction and the merchant continued to bill the cardholder or the cardholder was not aware they were agreeing to a recurring transaction.
DUPLICATE_TRANSACTION	The same transaction has been processed more than once, resulting in duplicate charges.
FRAUDULENT_PROCESSING	The cardholder is in possession and control of all valid cards, processed at least one legitimate face-to-face transaction, and denies making one or more additional face-to-face transactions at the same merchant location.
GOODS_OR_SERVICES_NOT_PROVIDED	The cardholder has been debited for goods or services that were to be shipped, delivered or otherwise provided and were not received by the expected delivery date.
LATE_PRESENTMENT	The transaction was authorized offline by the chip and submitted for clearing more than 7 calendar days after the transaction date.
PAID_BY_OTHER_MEANS	The cardholder used a different form of payment for this specific transaction. (Mastercard pre-compliance/compliance only)
TRANSACTION_AMOUNT_DIFFERS	The amount of the transaction does not match the agreed-upon or expected amount.
TRANSACTION_DID_NOT_COMPLETE	The cardholder engaged in the transaction and claims it did not complete. Goods or services were not provided.
TRANSACTION_NOT_RECOGNIZED	The account holder does not recognize the transaction, possibly due to mistake or fraud.
UNAUTHORIZED_TRANSACTION	The transaction was not authorized by the account holder.

Card Dispute Lifecycle States

Chargeback Lifecycle

Lifecycle	Description
DENIED	The dispute has been denied.
PENDING_ACTION	A dispute has been created and is pending subsequent action.
WRITE_OFF	The dispute has been written off and will not be filed with the card network.
CHARGEBACK	A chargeback has been created with the card network. The acquiring bank now has the opportunity to file for re-presentment. If no re-presentment is filed the acquirer assumes financial responsibility and the case is won.
NETWORK_REJECTED_CHARGEBACK	The chargeback submission has been rejected by the card network. The chargeback can be optionally resubmitted once the rejection reason has been addressed.
NETWORK_REJECTED_CHARGEBACK_REVERSAL	The chargeback reversal has been rejected by the card network.
REPRESENTMENT	The acquiring bank has created a re-presentment with the card network. The issuing bank now has the opportunity to file for pre-arbitration. If no pre-arbitration is filed the issuer assumes financial responsibility and the case is lost.
PRE_ARBITRATION	A pre-arbitration case has been created with the network. The acquiring bank now has the opportunity to rebut the case with subsequent evidence. If no rebuttal is filed the acquirer assumes financial responsibility and the case is won.
PRE_ARBITRATION_RESPONSE	The acquiring bank has rebutted the pre-arbitration case. The issuing bank now has the opportunity to file for arbitration. If no arbitration case is filed the issuer assumes financial responsibility and the case is lost.
ARBITRATION	An arbitration case has been created with the card network. The acquiring bank now has the opportunity to rebut the arbitration case with subsequent evidence.
ARBITRATION_RESPONSE	The acquiring bank has rebutted the arbitration case. The issuing bank can either withdraw the case or do nothing and the card network will make a decision on who assumes the financial responsibility.

Compliance Lifecycle

Lifecycle	Description
PRE_COMPLIANCE	A pre-compliance case has been created by either the issuer or acquirer.
PRE_COMPLIANCE_RESPONSE	The opposing party has rebutted the pre-compliance case with further evidence.
COMPLIANCE	The initiating party has escalated the pre-compliance case to compliance.
COMPLIANCE_RESPONSE	The opposing party has rebutted the compliance case with further evidence.

Action History

Available Issuer Actions

Based on the lifecycle state of a dispute a set of available actions will be provided in the response of the dispute. At any point a subsequent action can be taken to either accept financial responsibility of the dispute or continue to pursue the dispute further.

Lifecycle	Action	State	Decision	Description
PENDING_ACTION	WRITE_OFF	CREATE	RESOLVED	Write off the dispute without filing on the card network.
PENDING_ACTION	CHARGEBACK	CREATE	ONGOING	File a chargeback with the card network.
CHARGEBACK	CHARGEBACK	REVERSE	LOST	Withdraw the chargeback case.
REPRESENTMENT	REPRESENTMENT	ACCEPT	LOST	Accept financial responsibility of the dispute after reviewing the evidence of the re-presentment.
REPRESENTMENT	PRE_ARBITRATION	CREATE	ONGOING	File a pre-arbitration case with the network.
PRE_ARBITRATION	PRE_ARBITRATION	REVERSE	LOST	Withdraw the pre-arbitration case.
PRE_ARBITRATION_RESPONSE	PRE_ARBITRATION	REVERSE	LOST	Withdraw the pre-arbitration case after reviewing the evidence in the pre-arbitration response.
PRE_ARBITRATION_RESPONSE	ARBITRATION	CREATE	ONGOING	File an arbitration case with the network.
ARBITRATION	ARBITRATION	REVERSE	LOST	Withdraw the arbitration case.
ARBITRATION_RESPONSE	ARBITRATION	REVERSE	LOST	Withdraw the arbitration case after reviewing the evidence in the arbitration response.

Acquirer Actions

Based on the lifecycle state of a dispute a set of actions can be received from the network and will be reflected through the dispute webhooks.

Lifecycle	Action	State	Decision	Description
CHARGEBACK	CHARGEBACK	ACCEPT	WON	Chargeback was accepted by the acquiring bank.
CHARGEBACK	REPRESENTMENT	CREATE	ONGOING	The acquiring bank has filed a re-presentment with the card network.
REPRESENTMENT	REPRESENTMENT	REVERSE	WON	The acquiring bank has withdrawn the re-presentment.
PRE_ARBITRATION	PRE_ARBITRATION	REBUT	ONGOING	The acquiring bank has rebutted the pre-arbitration case with further evidence.
PRE_ARBITRATION	PRE_ARBITRATION	ACCEPT	WON	The acquiring bank has accepted financial responsibility of the dispute after reviewing the evidence in the pre-arbitration case.
ARBITRATION	ARBITRATION	REBUT	ONGOING	The acquiring bank has rebutted the arbitration case with further evidence.
ARBITRATION	ARBITRATION	ACCEPT	WON	The acquiring bank has accepted financial responsibility of the dispute after reviewing the evidence in the arbitration case.

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
CA	Consumer	Debit/Prepaid	N/A
CA	Consumer	Credit	N/A
CA	Commercial	Debit/Prepaid	N/A
CA	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 (US and CA) - 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 will walk through an example card dispute that resulted in a case lost in the representment lifecycle.

1. Dispute Created

A dispute is created on behalf of the cardholder.

Request

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

Response

{
  "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"
    },
    {
      "action": "PRE_COMPLIANCE",
      "state": "CREATE",
      "timestamp_valid_to": "2024-07-24T00:00:00Z"
    }
  ],
  "lifecycle_state": "PENDING_ACTION",
  "network_eligibility": {
    "is_digital_wallet_token": false,
    "is_three_ds": false
  },
  "reason_code": "DUPLICATE_TRANSACTION"
}

2. Chargeback Action

Supporting documentation providing evidence for the chargeback is uploaded to the dispute.

Request

curl \
-X POST 
$baseurl/v1/disputes/{$dispute_id}/documents \ 
-H "Authorization: Bearer $apiKey" \ 
-F [email protected]

Response

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

The chargeback action is created with the supporting documentation.

Request

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

Dispute State

At this point the dispute reflects the chargeback action, timelines and regulations for provisional credits and any subsequent actions that can be taken by the issuer on the dispute.

{
  "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"
    }
  ],
  "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"
    }
  ],
  "available_actions": [
    {
      "action": "PROVISIONAL_CREDIT",
      "state": "CREATE"
    },
    {
      "action": "CHARGEBACK",
      "state": "REVERSE"
    }
  ],
  "lifecycle_state": "CHARGEBACK",
  "network_eligibility": {
    "is_digital_wallet_token": false,
    "is_three_ds": false
  },
  "reason_code": "DUPLICATE_TRANSACTION"
}

3. Post Provisional Credit

Request

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

Dispute State

The dispute now reflects the new provisional credit state.

{
  "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",
      "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": "PROVISIONAL_CREDIT",
      "creation_time": "2024-05-30T20:26:10.544524Z",
      "id": "018fcb2f-50f4-7514-a82d-e6143f57f25f",
      "payment_rail": "CARD",
      "status": "SUBMITTED",
      "tenant": "asbght_iujkio"
    }
  ],
  "available_actions": [
    {
      "action": "PROVISIONAL_CREDIT",
      "state": "REVERSE"
    },
    {
      "action": "CHARGEBACK",
      "state": "REVERSE"
    }
  ],
  "lifecycle_state": "CHARGEBACK",
  "network_eligibility": {
    "is_digital_wallet_token": false,
    "is_three_ds": false
  },
  "reason_code": "DUPLICATE_TRANSACTION"
}

4. Webhook Received for Representment

Dispute State

The dispute now reflects the new representment state with the supporting documentation received from the network.

{
  "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",
      "tenant": "asbght_iujkio"
    },
    {
      "creation_time": "2024-05-230T22:56:12.921781Z",
      "dispute_id": "018fc167-7672-729d-8d43-653518f3d939",
      "file_name": "file.pdf",
      "id": "018fcb30-90a1-7221-9160-28917c2cfc2d",
      "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": "PROVISIONAL_CREDIT",
      "creation_time": "2024-05-30T20:26:10.544524Z",
      "id": "018fcb2f-50f4-7514-a82d-e6143f57f25f",
      "payment_rail": "CARD",
      "status": "SUBMITTED",
      "tenant": "asbght_iujkio"
    },
    {
      "id": "018e62f5-8141-708f-a924-c706d82876a5",
      "creation_time": "2024-05-30T20:32:03.787519Z",
      "payment_rail": "CARD",
      "action": "REPRESENTMENT",
      "state": "CREATE",
      "supporting_doc_id": "018fcb30-90a1-7221-9160-28917c2cfc2d",
      "message": "Some things about re-presentment",
      "tenant": "paxqlw_poldeo"
    }
  ],
  "available_actions": [
    {
      "action": "PROVISIONAL_CREDIT",
      "state": "REVERSE"
    },
    {
      "action": "REPRESENTMENT",
      "state": "ACCEPT"
    },
    {
      "action": "PRE_ARBITRATION",
      "state": "CREATE"
    }
  ],
  "lifecycle_state": "REPRESENTMENT",
  "network_eligibility": {
    "is_digital_wallet_token": false,
    "is_three_ds": false
  },
  "reason_code": "DUPLICATE_TRANSACTION"
}

5. Representment Accepted

Request

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

Dispute State

The dispute now reflects the final decision and new provisional credit state which is reversed upon the decision to accept financial responsibility of the dispute.

{
  "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": "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",
      "tenant": "asbght_iujkio"
    },
    {
      "creation_time": "2024-05-230T22:56:12.921781Z",
      "dispute_id": "018fc167-7672-729d-8d43-653518f3d939",
      "file_name": "file.pdf",
      "id": "018fcb30-90a1-7221-9160-28917c2cfc2d",
      "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": "PROVISIONAL_CREDIT",
      "creation_time": "2024-05-30T20:26:10.544524Z",
      "id": "018fcb2f-50f4-7514-a82d-e6143f57f25f",
      "payment_rail": "CARD",
      "status": "SUBMITTED",
      "tenant": "asbght_iujkio"
    },
    {
      "id": "018e62f5-8141-708f-a924-c706d82876a5",
      "creation_time": "2024-05-30T20:32:03.787519Z",
      "payment_rail": "CARD",
      "action": "REPRESENTMENT",
      "state": "CREATE",
      "supporting_doc_id": "018fcb30-90a1-7221-9160-28917c2cfc2d",
      "message": "Some things about re-presentment",
      "tenant": "asbght_iujkio"
    },
    {
      "id": "018e62fa-4e7a-7814-9634-e130c66f6444",
      "creation_time": "2024-05-31T20:32:03.787519Z",
      "payment_rail": "CARD",
      "action": "REPRESENTMENT",
      "state": "ACCEPT",
      "tenant": "asbght_iujkio"
    }
  ],
  "available_actions": [
    {
      "action": "PRE_COMPLIANCE",
      "state": "CREATE",
      "timestamp_valid_to": "2024-07-24T00:00:00Z"
    }
  ],
  "lifecycle_state": "REPRESENTMENT",
  "network_eligibility": {
    "is_digital_wallet_token": false,
    "is_three_ds": false
  },
  "reason_code": "DUPLICATE_TRANSACTION"
}

6. Close Dispute

Request

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.

Network dispute simulations must follow the logical order of the dispute lifecyle, for example following a chargeback submission a representment can be simulated. For a complete list of potential actions that can be received from the network refer to acquirer actions.

In order to progress a dispute to the next lifecycle and simulate the a response from the dispute network, use POST /v1/disputes/simulations/{$dispute_id}/actions.

curl \ 
-X POST \ 
$baseurl/v1/disputes/simulations/{$dispute_id}/actions \ 
-H "Authorization: Bearer $apiKey" \ 
--json '
{
  "payment_rail": "CARD",
  "action": "REPRESENTMENT",
  "state": "CREATE",
  "message": "Some things about representment" 
}
'

Overview

What Transactions Can Be Disputed?

Network Eligibility

Chargeback Dispute Lifecycle

1. Chargeback

2. Representment

3. Pre-arbitration

4. Arbitration

Compliance Lifecycle

Pre-compliance

Compliance

Write Offs

Dispute Networks

📘Available Networks

Reason Code

Card Dispute Lifecycle States

Chargeback Lifecycle

Compliance Lifecycle

Action History

Available Issuer Actions

Acquirer Actions

Provisional Credits

To Summarize:

Complex Business Flow Example

1. Dispute Created

Request

Response

2. Chargeback Action

Request

Response

Request

Dispute State

3. Post Provisional Credit

Request

Dispute State

4. Webhook Received for Representment

Dispute State

5. Representment Accepted

Request

Dispute State

6. Close Dispute

Request

Simulating Network Dispute Actions

🚧Sandbox Environment Only

📘
Available Networks

🚧
Sandbox Environment Only