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)?_[0-9a-z]+/.

livemode boolean

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

location string

API path to retrieve the current dispute object.

admin_message string

Admin message added to dispute providing additional context.

amount integer

Amount for dispute in smallest currency unit.

charge object_id

CHARGE_ID associated with the dispute.

closed_at datetime

UTC datetime of the closure (i.e. won or lost) of the dispute in ISO 8601 format.

created datetime

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

currency string

Currency for dispute as three-letter ISO 4217 code.

documents list

List of documents uploaded as part of this dispute.

message string

Explanation for the dispute.

metadata Object

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

reason_code string

Dispute reason code.

reason_message string

Dispute message associated with the dispute reason 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

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) Offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) Number of records to return.

from datetime

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

to datetime

(optional, default: current UTC datetime) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) Order in which to return records. One of 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) Offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) Number of records to return.

from datetime

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

to datetime

(optional, default: current UTC datetime) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) Order in which to return records. One of 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) Offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) Number of records to return.

from datetime

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

to datetime

(optional, default: current UTC datetime) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) Order in which to return records. One of 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) Offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) Number of records to return.

from datetime

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

order string

(optional, default: chronological) Order in which to return records. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

to datetime

(optional, default: current UTC datetime) Latest UTC datetime 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}) to attach to the dispute.

Example

  • Update a dispute