Transaction Disputes

Overview

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

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

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

Webhook Events

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

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

To subscribe to the dispute webhooks refer to the Webhooks Guide.

Disputing a Transaction

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

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

Card Transaction Disputes

1. Create a Dispute

To create a dispute, use POST /v1/disputes.

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

This will return a response with the created 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": [],
  "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"
}

Note the returned id attribute and the list of available_actions.

2. Upload Supporting Documents

To add supporting documentation to the dispute, use POST /v1/disputes/{dispute_id}/documents

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

This will return a response with the created document.

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

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

3. Create a Dispute Action

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

To create the action, use POST /v1/disputes/{$dispute_id}/actions

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

This will return a response with the created action.

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

4. Monitor for Network Updates

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

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

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

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

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

5. Review Additional Supporting Documents

To retrieve supporting documentation from the dispute, use GET /v1/disputes/documents/{document_id}/contents

curl \
-X GET 
$baseurl/v1/disputes/{$document_id}/contents \ 
-H "Authorization: Bearer $apiKey" \ 
-o file.pdf

6. File Additional Actions as Needed

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

7. Close Dispute

To close the dispute, use PATCH /v1/disputes/{dispute_id}

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