Dispute API

The Dispute API allows you to retrieve and update disputes. Disputes can be initiated by customers through their card issuer if there is some problem with a given charge for which the customer requests a reversal. A given dispute can contain a list or supporting documents. Disputes can have one of the following statuses: open, pending, won, or lost.

Attribute

Name Type Description
object string

The string dispute.

id object_id

The DISPUTE_ID matching /dspt(_test)?_[1-9a-z]+/.

livemode boolean

Whether this is a live (true) or test (false) dispute.

location string

API path to retrieve the current dispute object.

amount integer

The amount expressed as a positive integer in the smallest unit for the currency (e.g. 100 satangs equals THB 1). See supported currencies by country for maximum and minimum.

charge object_id

The CHARGE_ID associated with the dispute.

closed_at datetime

When the dispute was closed (i.e. won or lost) in ISO 8601 datetime format.

created datetime

The UTC datetime of the creation of the dispute in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

currency string

The currency expressed as its lower-cased international 3-letter code defined by the ISO 4217 standard (see supported currencies by country).

documents list

List of documents uploaded as part of this dispute.

message string

The dispute message. A short explanation for the dispute.

metadata Object

Custom metadata (e.g. {"customer-id": 42}) for dispute.

reason_code string

The dispute code.

reason_message string

The dispute message associated with the dispute code.

status string

The dispute status. One of open, pending, won or lost. (note: won and lost disputes are retrievable using the /disputes/closed endpoint).

transaction object_id

The TRANSACTION_ID associated with this dispute.

Example

  • Json Response

List all disputes

- GET https://api.omise.co/disputes

Returns a list of all dispute objects belonging to your account.

Request Parameter

Name Type Description
offset integer

(optional, default: 0) The offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) The number of records returned.

from datetime

(optional, default: 1970-01-01T00:00:00Z) The earliest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

to datetime

(optional, default: current UTC datetime) The latest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) The order in which the records are returned. Either chronological (earliest to latest) or reverse_chronological (latest to earliest).

Example

  • List all disputes

List all open disputes

- GET https://api.omise.co/disputes/open

Returns a list of open dispute objects.

Request Parameter

Name Type Description
offset integer

(optional, default: 0) The offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) The number of records returned.

from datetime

(optional, default: 1970-01-01T00:00:00Z) The earliest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

to datetime

(optional, default: current UTC datetime) The latest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) The order in which the records are returned. Either chronological (earliest to latest) or reverse_chronological (latest to earliest).

Example

  • List all open disputes

List all pending disputes

- GET https://api.omise.co/disputes/pending

Returns a list of pending dispute objects.

Request Parameter

Name Type Description
offset integer

(optional, default: 0) The offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) The number of records returned.

from datetime

(optional, default: 1970-01-01T00:00:00Z) The earliest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

to datetime

(optional, default: current UTC datetime) The latest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) The order in which the records are returned. Either chronological (earliest to latest) or reverse_chronological (latest to earliest).

Example

  • List all pending disputes

List all closed disputes

- GET https://api.omise.co/disputes/closed

Returns a list of closed (won or lost) dispute objects.

Request Parameter

Name Type Description
offset integer

(optional, default: 0) The offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) The number of records returned.

from datetime

(optional, default: 1970-01-01T00:00:00Z) The earliest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) The order in which the records are returned. Either chronological (earliest to latest) or reverse_chronological (latest to earliest).

to datetime

(optional, default: current UTC datetime) The latest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Example

  • List all closed disputes

Retrieve a dispute

- GET https://api.omise.co/disputes/DISPUTE_ID

Returns a dispute object.

Example

  • Retrieve a dispute

Update a dispute

- PATCH https://api.omise.co/disputes/DISPUTE_ID

Returns the updated dispute object. Only open disputes can be updated, and updating a dispute changes its status to pending.

Request Parameter

Name Type Description
message string

(required) The dispute message

metadata Object

(optional) Custom metadata (e.g. {"customer-id": 42}) for dispute.

Example

  • Update a dispute