Dispute API

Retrieve and update disputes. Disputes can be initiated by customers through their card issuer if they determine there is some problem with a given charge. A given dispute can contain a list of supporting documents. Disputes can have one of the following statuses: open, pending, won, or lost.

Attributes

Name Type Description
object string

The string dispute.

id object_id

The dispute identifier 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

Message added to dispute providing additional context for administrator.

amount integer

Dispute amount in smallest unit of dispute currency.

charge object_id

Charge identifier associated with the dispute.

closed_at datetime

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

created datetime

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

currency currency_lowercase

Currency for dispute as three-letter ISO 4217 code.

documents list

List of supporting documents uploaded to dispute.

message string

Explanation for dispute.

metadata object

Custom metadata (e.g. {"answer": 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 identifier associated with this dispute.

Example

  • JSON Response

Retrieve a dispute

- GET https://api.omise.co/disputes/{id}

Returns the dispute matching :id.

Example

  • Retrieve a dispute

Update a dispute

- PATCH https://api.omise.co/disputes/{id}

Returns the updated dispute matching :id. Only open disputes can be updated, and updating a dispute message changes its status to pending.

Request Parameters

Name Type Description
message string

(optional) Explanation for dispute.

metadata object

(optional) Custom metadata (e.g. {"answer": 42}) for dispute.

Example

  • Update dispute message

  • Update dispute message and metadata

List disputes

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

Returns a list of disputes belonging to your account.

Request Parameters

Name Type Description
from datetime

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

limit integer

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

offset integer

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

order string

(optional, default: chronological) Order of records returned. 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 disputes

Accept a dispute

- GET https://api.omise.co/disputes/{id}/accept

Accepts the dispute matching :id. Only for test mode.

Example

  • Accept a dispute

List closed disputes

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

Returns a list of closed (won or lost) disputes belonging to your account.

Request Parameters

Name Type Description
from datetime

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

limit integer

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

offset integer

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

order string

(optional, default: chronological) Order of records returned. 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

List open disputes

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

Returns a list of open disputes belonging to your account.

Request Parameters

Name Type Description
from datetime

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

limit integer

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

offset integer

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

order string

(optional, default: chronological) Order of records returned. 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 open disputes

List pending disputes

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

Returns a list of pending disputes belonging to your account.

Request Parameters

Name Type Description
from datetime

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

limit integer

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

offset integer

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

order string

(optional, default: chronological) Order of records returned. 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 pending disputes