​
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. 
curl -X GET ${API_BASE_URL}/disputes/categories \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "signature: ${SIGNATURE}"

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

​
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. 
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"
      }
    ]
  }'

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

​
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. 
curl -X GET ${API_BASE_URL}/disputes/DISP1234567890 \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "signature: ${SIGNATURE}"

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

​
Dispute Status Types

The dispute management system tracks disputes through various statuses:
StatusDescription
LOGGEDDispute has been successfully submitted and logged
PROCESSINGDispute is under investigation and review
ON_HOLDDispute resolution is temporarily paused
RESOLVEDDispute has been resolved and closed
CANCELLEDDispute has been cancelled by the customer or system
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.

​
Next Steps

Now that you understand dispute management operations, explore these related topics:
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.
⌘I