This tutorial will guide you through the process of managing the dispute using Mbanq Cloud APIs and explain the flow for raising the dispute for transactions with below-mentioned supported four payment rails.

ACH
Debit Card
Credit Card
External Card

In this tutorial, we will walk you through the steps involved in creating the dispute and performing various operations using the MBanq Cloud Dispute API.

📘
API References for Dispute Management in this tutorial:

Get Dispute Reason Workflow

Create Dispute

The curl statements below will demonstrate the API requests and responses. Let's get started!

Step 1: Retrieve Dispute Reasons

Fetch the dispute reasons configured in the platform use the Get Dispute Reasons API

The response of this API will include the details of the dispute reasons.

{
  "totalFilteredRecords": 2,
  "pageItems": [
    {
      "id": 1,
      "name": "POS UNAUTHORIZED FRAUD",
      "supportRecognizedTransaction": true,
      "description": "Dispute Reason For POS_UNAUTHORIZED_FRAUD",
      "reasonIdentifier": "POS_UNAUTHORIZED_FRAUD",
      "supportMultipleTransactions": true,
      "paymentRail": "DEBIT_CARD"
    },
    {
      "id": 2,
      "name": "POS Incorrect Amount",
      "supportRecognizedTransaction": true,
      "description": "Incorrect Amount Charged",
      "reasonIdentifier": "Incorrect Amount Charged",
      "supportMultipleTransactions": true,
      "paymentRail": "CREDIT_CARD"
    }
  ]
}

Parameter	Value Type	Example Value	Explanation
id	Integer	1	Unique Id for each dispute reason.
name	String	POS UNAUTHORIZED FRAUD	Name of the .dispute reason.
description	String	POS UNAUTHORIZED FRAUD	Description of the dispute reason.
reasonIdentifier	String	POS_UNAUTHORIZED_FRAUD	Unique Identifier for dispute reason, used for dispute creation.
paymentRail	String	DEBIT_CARD, CREDIT_CARD	Associated payment rail for the dispute reason.
supportMultipleTransactions	Boolean	false	Flag for dispute reason support for multiple transactions.
supportRecognizedTransaction	Boolean	false	Flag for dispute reason for support of recognized transactions.

Step 2: Retrieve Dispute Reason Workflow

Fetch the workflow configured in the platform for the particular dispute reason use the Get Dispute Reason Workflow API using the reasonIdentifier fetched from the Step 1 API response .

The response of this API includes the details of the workflow step configured for the dispute.

{
  "id": 1,
  "name": "POS UNAUTHORIZED FRAUD",
  "supportRecognizedTransaction": true,
  "description": "Non receipt of merchandise",
  "reasonIdentifier": "POS_UNAUTHORIZED_FRAUD",
  "supportMultipleTransactions": true,
  "paymentRail": "DEBIT_CARD",
  "workflow": [
    {
      "step": 1,
      "type": "NORMAL",
      "fields": [
        {
          "id": 1,
          "label": "Please provide amount of the dispute",
          "required": true,
          "inputTypeName": "INPUT_AMOUNT",
          "note": "a note for the field",
          "fieldIdentifier": "duplicate_charge_dispute_description",
          "disputeConfigurationRadioOptions": []
        },
        {
          "id": 2,
          "label": "input date",
          "required": true,
          "inputTypeName": "INPUT_DATE",
          "fieldIdentifier": "input_date_field",
          "disputeConfigurationRadioOptions": []
        },
        {
          "id": 3,
          "label": "input file is always optional",
          "required": true,
          "inputTypeName": "INPUT_FILE",
          "note": "File Input",
          "fieldIdentifier": "input_file",
          "disputeConfigurationRadioOptions": []
        },
        {
          "id": 4,
          "label": "Options",
          "required": false,
          "inputTypeName": "INPUT_RADIO",
          "note": "Options",
          "fieldIdentifier": "radio_options",
          "disputeConfigurationRadioOptions": [
            {
              "label": "xx",
              "value": "VAL"
            }
          ]
        }
      ],
      "nextStep": 2
    },
    {
      "step": 2,
      "type": "SUBMIT",
      "fields": [
        {
          "id": 5,
          "label": "Thank you for submitting your dispute. You should now receive a confirmation via telephone that we have on file. If you do not receive a confirmation during next 5 minutes, please reach out to our user care.",
          "required": false,
          "fieldIdentifier": "field_identifier_for_submit",
          "disputeConfigurationRadioOptions": []
        }
      ]
    }
  ]
}

Step 3: Create Dispute

Use the Create Dispute API for the dispute initiated based on the workflow step fetch from the Step 2 API response.

Parameter	Value Type	Example Value	Explanation
reasonIdentifier	Integer	POS_UNAUTHORIZED_FRAUD	Unique identifier of the dispute reason.
transactions	JSON	[{"transactionId": 2}]	Details for the dispute transaction
accountType	String	DEPOSIT	Type of the account for the disputed transaction.
accountId	Integer	12	Unique Identifier for the account associated with the transaction.
workflowData	JSON	[{"fieldIdentifier": "disputeDate","value" : "2024-01-01"}]	Workflow data for the entered by the user for dispute.

On the successful response will include the details of the unique identifier created for the dispute in the platform.

{
  "resourceId": "DISP-G1722-B5045-C7550-X8"
}

Tutorial: Dispute Management API

📘
API References for Dispute Management in this tutorial:

Step 1: Retrieve Dispute Reasons

Step 2: Retrieve Dispute Reason Workflow

Step 3: Create Dispute

📘API References for Dispute Management in this tutorial:

Step 1: Retrieve Dispute Reasons

Step 2: Retrieve Dispute Reason Workflow

Step 3: Create Dispute

📘
API References for Dispute Management in this tutorial: