> ## Documentation Index
> Fetch the complete documentation index at: https://docs-sandbox.sparkle.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Dispute Management

> Learn how to manage disputes and implement dispute resolution flows

## Dispute Management Guide

This guide covers everything you need to know about managing disputes in your Open Banking application. Our dispute management API provides comprehensive tools for reporting disputes, tracking their status, and managing the resolution process.

## Overview

Dispute management is a critical component of financial services that allows customers to report and track issues with their transactions. Our API supports a complete dispute lifecycle from initial reporting to final resolution, ensuring transparency and accountability in financial operations.

## Key Dispute Operations

### 1. Get Dispute Categories

Retrieve available dispute categories to help customers properly categorize their disputes. This operation returns a list of predefined categories that customers can choose from when reporting a dispute.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X GET ${API_BASE_URL}/disputes/categories \
      -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
      -H "signature: ${SIGNATURE}"
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "status": "00",
    "message": "Dispute categories retrieved successfully",
    "data": {
      "dispute_categories": [
        {
          "id": "1213123",
          "name": "Internet Service Providers",
          "description": "Internet and data service providers including ISPs and Telcos"
        },
        {
          "id": "1213124",
          "name": "Banking Services",
          "description": "Banking and financial service related disputes"
        },
        {
          "id": "1213125",
          "name": "Utility Bills",
          "description": "Electricity, water, and other utility service disputes"
        }
      ]
    }
  }
  ```
</Accordion>

### 2. Report a Dispute

Submit a new dispute report with detailed information about the issue. This operation creates a dispute record and initiates the resolution process.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST ${API_BASE_URL}/disputes \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
      -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
      -H "signature: ${SIGNATURE}" \
      -d '{
        "reference": "DISP1234567890",
        "description": "Unauthorized transaction on my account",
        "customer_id": "CUS1234567890",
        "dispute_category_id": "1213124",
        "amount": 100.00,
        "custom_properties": [
          {
            "id": "transaction_id",
            "description": "Original transaction reference",
            "type": "reference",
            "value": "TXN123456789"
          }
        ]
      }'
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "status": "00",
    "message": "The process was completed successfully",
    "data": {
      "report_reference": "DISP1234567890",
      "report_status": "LOGGED",
      "first_response_sla": "24 hours",
      "resolution_sla": "7 days",
      "follow_up_email": "support@example.com",
      "follow_up_phone": "+2348012345678",
      "custom_properties": [
        {
          "id": "transaction_id",
          "description": "Original transaction reference",
          "type": "reference",
          "value": "TXN123456789"
        }
      ]
    }
  }
  ```
</Accordion>

### 3. Get Dispute Status

Retrieve the current status of a specific dispute using the report reference. This operation provides real-time updates on the dispute resolution process.

<Accordion title="Sample Request">
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X GET ${API_BASE_URL}/disputes/DISP1234567890 \
      -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
      -H "signature: ${SIGNATURE}"
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Sample Response">
  ```json theme={null}
  {
    "status": "00",
    "message": "Dispute status retrieved successfully",
    "data": {
      "report_reference": "DISP1234567890",
      "report_status": "PROCESSING",
      "first_response_sla": "24 hours",
      "resolution_sla": "7 days",
      "follow_up_email": "support@example.com",
      "follow_up_phone": "+2348012345678",
      "custom_properties": [
        {
          "id": "transaction_id",
          "description": "Original transaction reference",
          "type": "reference",
          "value": "TXN123456789"
        }
      ]
    }
  }
  ```
</Accordion>

## Dispute Status Types

The dispute management system tracks disputes through various statuses:

| Status         | Description                                          |
| -------------- | ---------------------------------------------------- |
| **LOGGED**     | Dispute has been successfully submitted and logged   |
| **PROCESSING** | Dispute is under investigation and review            |
| **ON\_HOLD**   | Dispute resolution is temporarily paused             |
| **RESOLVED**   | Dispute has been resolved and closed                 |
| **CANCELLED**  | Dispute has been cancelled by the customer or system |

<Note>
  Make sure you send the appropriate scopes while requesting for a token: `disputes.categories.list`, `disputes.report.create`, and `disputes.report.readonly`. Failure to include these scopes will prevent access to the dispute management APIs.
</Note>

## Next Steps

Now that you understand dispute management operations, explore these related topics:

* [Developer Onboarding](/guides/developer-onboarding) - Onboard Developer
* [Customer Management](/guides/customers) - Manage customer information and relationships
* [Account Management](/guides/account) - Manage bank accounts and balances
* [Transfers](/guides/transfers) - Process money transfers between accounts
* [Bill Payment](/guides/bill-payment) - Process utility and bill payments
* [Card Management](/guides/card-management) - Manage Payment Cards
* [Direct Debit Management](/guides/direct-debit) - Manage Payment Cards
* [Savings Information](/guides/savings-information) - Manage Payment Cards
* [Loan Information](/guides/loans) - Access customer Loan Information

<Button href="/api-reference/registration" size="sm">
  Explore API Reference
</Button>

<Note>
  Always ensure proper consent and authorization before performing dispute operations. Implement robust error handling and maintain detailed audit trails for all dispute-related activities. Regular monitoring and compliance with regulatory requirements are essential for successful dispute management implementation.
</Note>