Dispute Management

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.

Sample Request

curl -X GET ${API_BASE_URL}/disputes/categories \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "signature: ${SIGNATURE}"

Sample Response

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

Sample Request

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

Sample Response

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

Sample Request

curl -X GET ${API_BASE_URL}/disputes/DISP1234567890 \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "signature: ${SIGNATURE}"

Sample Response

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

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

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:

Developer Onboarding - Onboard Developer
Customer Management - Manage customer information and relationships
Account Management - Manage bank accounts and balances
Transfers - Process money transfers between accounts
Bill Payment - Process utility and bill payments
Card Management - Manage Payment Cards
Direct Debit Management - Manage Payment Cards
Savings Information - Manage Payment Cards
Loan Information - Access customer Loan Information

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.

Overview

Getting Started

Product Guide

Support