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 string

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_expandable

Charge identifier associated with the dispute.

closed_at string

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

created_at string

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

currency string

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 string

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

merchant_name string

The name of the sub-merchant who initiated the dispute.

Note: This field is applicable only if the merchant uses the Payfac solution. To enroll in Payfac, contact Opn Support

merchant_uid string

The ID of the sub-merchant who initiated the dispute.

Note: This field is applicable only if the merchant uses the Payfac solution. To enroll in Payfac, contact Opn Support

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

Accept a dispute

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

Accepts the dispute matching :id.

Example

  • Accept a dispute

Close a dispute

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

Closes the dispute with status open or pending and matching :id with the new status won or lost.

Request Parameters

Name Type Description
status string

(optional, one of: won, lost) The desired dispute closure status. One of won or lost.

Example

  • Close 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 string

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

to string

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

Example

  • List all closed disputes

Create a dispute

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

Returns the created dispute for charge matching :id.

Example

  • Create dispute

List disputes

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

Returns a list of disputes belonging to your account.

Request Parameters

Name Type Description
from string

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

to string

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

Example

  • List all 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 string

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

to string

(optional) 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 string

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

to string

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

Example

  • List all pending disputes

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

Omise uses cookies to improve your overall site experience and collect information on your visits and browsing behavior. By continuing to browse our website, you agree to our Privacy Policy. Learn more