Dispute API

Dispute API ใช้เพื่อเรียกดูและอัปเดตรายการที่ผู้ถือบัตรปฏิเสธรายการ โดยการปฏิเสธรายการ (dispute) เกิดขึ้นจากการที่ผู้ถือบัตรติดต่อกับทางธนาคารผู้ออกบัตรโดยตรงเพื่อขอให้ยกเลิกการทำรายการ ในกรณีแบบนี้ร้านค้าสามารถจัดการได้โดยส่งเอกสารหลักฐานเพื่อยืนยันความถูกต้องของรายการ โดยสามารถเลือกอัพโหลดผ่าน Document API สถานะของรายการเป็นได้ดังนี้: open (เปิด), pending (อยู่ระหว่างดำเนินการ), won (ชนะ) หรือ 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

Amount fundable to the merchant after exchange to funding_currency (if currency != funding_currency) in the smallest currency unit.

funding_currency currency

Currency of funding_amount.

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