Dispute API

The Dispute API allows you to 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

Amount for dispute in smallest currency unit.

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_at datetime

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

currency currency

Currency for dispute as three-letter ISO 4217 code.

documents list

List of supporting documents uploaded to dispute.

funding_amount integer

For multi-currency charges, amount after exchange into account funding currency (funding_currency) specified in the smallest unit of funding_currency.

For non-multi-currency charges, amount specified in the smallest unit of currency.

funding_currency currency

Currency for account as three-letter ISO 4217 code. This is the settlement currency for all charges.

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).

transactions array

Transactions associated with 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