List charge disputes

GEThttps://api.omise.co/charges/:id/disputes

List all disputes for a specific charge. Returns disputes sorted by creation date with pagination capabilities.

---

Request Parameters

Required - 1 fieldRequired Parameters

▼

`id`STRING(required)

The charge ID to retrieve disputes for. Must be a valid charge ID from your account.

Example:"chrg_test_5xuy4w91xqz7d1w9u0t"

Constraints:Must start with chrg_, Test charges: chrg_test_, Live charges: chrg_live_

Recommended - 3 fieldsRecommended Parameters

▼

`limit`INTEGER(optional)

Number of disputes to return per page.

Example:20

Constraints:Minimum: 1, Maximum: 100

Default:20

`offset`INTEGER(optional)

Number of disputes to skip for pagination. Use with limit to navigate through pages.

Example:0

Default:0

`order`STRING(optional)

Sort order by creation date.

Example:"chronological"

Values:chronological, reverse_chronological

Default:"chronological"

Additional - 2 fieldsAdditional Parameters

▼

---

Responses

200

Successful list retrieval

Returns a list object containing dispute data array and pagination metadata.

Response includes:

• data - Array of dispute objects
• total - Total number of disputes for this charge
• limit - Number of items per page
• offset - Current pagination offset
• order - Sort order applied
• from / to - Date range applied

400

Bad request

Invalid parameters provided.

Common causes:

• Invalid date format (must be ISO 8601)
• Limit out of range (must be 1-100)
• Invalid offset value

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key

404

Not found

Charge ID does not exist.

Common causes:

• Incorrect charge ID
• Charge from different account
• Using test key for live charge (or vice versa)

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/charges/chrg_test_5xuy4w91xqz7d1w9u0t/disputes?limit=20&offset=0" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

charge = Omise::Charge.retrieve('chrg_test_5xuy4w91xqz7d1w9u0t')
disputes = charge.disputes(limit: 20, offset: 0)

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

charge = omise.Charge.retrieve('chrg_test_5xuy4w91xqz7d1w9u0t')
disputes = charge.disputes(limit=20, offset=0)

Node.js

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

const disputes = await omise.charges.listDisputes('chrg_test_5xuy4w91xqz7d1w9u0t', {
  limit: 20,
  offset: 0
});

PHP

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

$charge = OmiseCharge::retrieve('chrg_test_5xuy4w91xqz7d1w9u0t');
$disputes = $charge->disputes(array(
    'limit' => 20,
    'offset' => 0
));

Java

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

ScopedList<Dispute> disputes = client.charges()
    .get("chrg_test_5xuy4w91xqz7d1w9u0t")
    .disputes()
    .limit(20)
    .offset(0)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var disputes = await client.Charges.ListDisputes("chrg_test_5xuy4w91xqz7d1w9u0t", new ListOptions {
    Limit = 20,
    Offset = 0
});

Go

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

disputes, _ := client.ListChargeDisputes("chrg_test_5xuy4w91xqz7d1w9u0t", &operations.ListChargeDisputes{
    List: operations.List{
        Limit:  20,
        Offset: 0,
    },
})

---

Error and result codes

Dispute Status Values

Status	Description	Next Steps
open	Dispute is open and pending resolution	Submit evidence via dashboard
pending	Evidence submitted, awaiting decision	Wait for card network decision
won	Dispute resolved in merchant's favor	Funds returned to merchant
lost	Dispute resolved in customer's favor	Funds debited from account

Pagination Calculation

Field	Calculation	Use
Next page	offset + limit	Get next set of results
Previous page	offset - limit (min 0)	Go back to previous page
Has more	offset + limit < total	Check if more pages exist
Page number	(offset / limit) + 1	Current page number

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

id(Required)

Recommended - 3 fields

▼

Additional - 2 fields

▼

Your IP: ...Loading...