Search Disputes

GEThttps://api.omise.co/disputes/search

Search disputes by various criteria including status, reason code, amount, currency, and date range. The Search API provides powerful filtering capabilities to find specific disputes across your account.

---

Request Parameters

Recommended - 2 fieldsRecommended Parameters

▼

`query`STRING(optional)

Search query string. Searches across dispute ID, charge ID, reason message, and metadata. Supports multiple words (AND logic) and partial matches.

Example:"fraudulent chrg_test_123"

`filters`OBJECT(optional)

Filter criteria to narrow search results. Common filters include status, reason_code, currency, amount, and created date ranges.

Example:{"status":"open","reason_code":"fraudulent","currency":"thb"}

Additional - 3 fieldsAdditional Parameters

▼

---

Responses

200

Successful search

Search completed successfully. Returns a search result object with matching disputes in the data array.

Response includes:

• data - Array of dispute objects matching the search criteria
• total - Total number of results matching the search
• total_pages - Number of pages available
• page - Current page number
• per_page - Number of results per page
• order - Sort order applied (chronological or reverse_chronological)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid page number (below 1)
• Invalid per_page value (above 100 or below 1)
• Malformed filters object
• Invalid filter field names

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/disputes/search \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "query=fraudulent" \
  -d "filters[status]=open" \
  -d "filters[reason_code]=fraudulent"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

results = Omise::Dispute.search({
  query: 'fraudulent',
  filters: {
    status: 'open',
    reason_code: 'fraudulent'
  }
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

results = omise.Dispute.search(
    query='fraudulent',
    filters={
        'status': 'open',
        'reason_code': 'fraudulent'
    }
)

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const results = await omise.disputes.search({
  query: 'fraudulent',
  filters: {
    status: 'open',
    reason_code: 'fraudulent'
  }
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$results = OmiseDispute::search([
    'query' => 'fraudulent',
    'filters' => [
        'status' => 'open',
        'reason_code' => 'fraudulent'
    ]
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Map<String, Object> filters = new HashMap<>();
filters.put("status", "open");
filters.put("reason_code", "fraudulent");

SearchResult<Dispute> results = client.disputes().search()
    .query("fraudulent")
    .filters(filters)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var results = await client.Disputes.Search(new SearchRequest
{
    Query = "fraudulent",
    Filters = new Dictionary<string, object>
    {
        { "status", "open" },
        { "reason_code", "fraudulent" }
    }
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

results, _ := client.SearchDisputes(&operations.SearchDisputes{
    Query: "fraudulent",
    Filters: map[string]interface{}{
        "status":      "open",
        "reason_code": "fraudulent",
    },
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Invalid parameters	Check that filters are valid and parameters are correct
authentication_failure	Invalid API key	Verify your secret key is correct
invalid_filter	Invalid filter field	Use valid filter fields (status, reason_code, currency, amount, created)

Search Filter Options

Filter	Type	Description
status	string	Dispute status (open, pending, won, lost)
reason_code	string	Reason code (fraudulent, unrecognized, duplicate, etc.)
currency	string	Currency code (thb, jpy, sgd, myr, usd, etc.)
amount	integer	Exact amount in smallest currency unit
created	object	Date range filter (e.g., {gte: '2025-01-01', lte: '2025-01-31'})

Reason Codes

Code	Description
fraudulent	Customer claims unauthorized transaction
unrecognized	Customer doesn't recognize the charge
duplicate	Customer claims duplicate charge
goods_or_services_not_provided	Product/service not received
not_as_described	Product significantly different from description
credit_not_processed	Refund promised but not received
general	Other reasons

---

🔑API Credentials

▼

Try it out

Recommended - 2 fields

▼

Additional - 3 fields

▼

Your IP: ...Loading...