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

{
  "object": "dispute",
  "id": "dspt_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "/disputes/dspt_test_no1t4tnemucod0e51mo",
  "currency": "THB",
  "amount": 12345,
  "funding_amount": 12345,
  "funding_currency": "THB",
  "metadata": {},
  "charge": "chrg_test_no1t4tnemucod0e51mo",
  "documents": {
    "object": "list",
    "data": [],
    "limit": 20,
    "offset": 0,
    "total": 0,
    "location": "/disputes/dspt_test_no1t4tnemucod0e51mo/documents",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2019-12-31T12:59:59Z"
  },
  "transactions": [
    {
      "object": "transaction",
      "id": "trxn_test_no1t4tnemucod0e51mo",
      "livemode": false,
      "currency": "THB",
      "amount": 12345,
      "location": "/transactions/trxn_test_no1t4tnemucod0e51mo",
      "direction": "debit",
      "key": "dispute.started.debit",
      "origin": "dspt_test_no1t4tnemucod0e51mo",
      "transferable_at": "2019-12-31T12:59:59Z",
      "created_at": "2019-12-31T12:59:59Z"
    }
  ],
  "admin_message": null,
  "message": null,
  "reason_code": "goods_or_services_not_provided",
  "reason_message": "Services not provided or Merchandise not received",
  "status": "open",
  "closed_at": null,
  "created_at": "2019-12-31T12:59:59Z"
}

Accept a dispute

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

Accepts the dispute matching :id.

Example

Accept a dispute

curl

curl https://api.omise.co/disputes/dspt_test_5g5ih3pybo7v4wwrbjw/accept \
  -X PATCH \
  -u $OMISE_SECRET_KEY:

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

curl

curl https://api.omise.co/disputes/dspt_test_5g5ih3pybo7v4wwrbjw/close \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "status=lost"

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

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/disputes/closed \
  -u $OMISE_SECRET_KEY:

<?php

$disputes = OmiseDispute::retrieve('closed');

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const dispute = await omise.disputes.listClosed();
console.log(dispute);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

disputes = Omise::Dispute.list(status: "closed")

var resource = Client.Disputes.ClosedDisputes;
var closedDisputes = await resource.GetList(order: Ordering.ReverseChronological);
Console.WriteLine($"closed disputes: {closedDisputes.Total}");

Request<ScopedList<Dispute>> request = new Dispute.ListRequestBuilder().status(DisputeStatus.Closed).build();
ScopedList<Dispute> disputes = client().sendRequest(request);

System.out.printf("Closed disputes: %d", disputes.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

dispute = omise.Dispute.retrieve(status="closed")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Dispute{}
err := client.Do(result, &operations.ListDisputes{
	State: omise.Closed})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Dispute.list(status: "closed")

Create a dispute

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

Returns the created dispute for charge matching :id.

Example

Create dispute

curl

curl https://api.omise.co/charges/chrg_test_5g5idked981unmzjzhl/disputes \
  -X POST \
  -u $OMISE_SECRET_KEY:

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

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/disputes \
  -u $OMISE_SECRET_KEY:

<?php

$disputes = OmiseDispute::retrieve();

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const dispute = await omise.disputes.list();
console.log(dispute);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

disputes = Omise::Dispute.list

var resource = Client.Disputes;
var disputes = await resource.GetList(order: Ordering.ReverseChronological);
Console.WriteLine($"total disputes: {disputes.Total}");

Request<ScopedList<Dispute>> request = new Dispute.ListRequestBuilder().build();
ScopedList<Dispute> disputes = client().sendRequest(request);

System.out.printf("Total no. of disputes: %d", disputes.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

disputes = omise.Dispute.retrieve()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Dispute{}
err := client.Do(result, &operations.ListDisputes{})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Dispute.list

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

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/disputes/open \
  -u $OMISE_SECRET_KEY:

<?php

$disputes = OmiseDispute::retrieve('open');

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const dispute = await omise.disputes.listOpen();
console.log(dispute);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

disputes = Omise::Dispute.list(status: "open")

var resource = Client.Disputes.OpenDisputes;
var openDisputes = await resource.GetList(order: Ordering.ReverseChronological);
Console.WriteLine($"open disputes: {openDisputes.Total}");

Request<ScopedList<Dispute>> request = new Dispute.ListRequestBuilder().status(DisputeStatus.Open).build();
ScopedList<Dispute> disputes = client().sendRequest(request);

System.out.printf("Open disputes: %d", disputes.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

dispute = omise.Dispute.retrieve(status="open")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Dispute{}
err := client.Do(result, &operations.ListDisputes{
	State: omise.Open,
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Dispute.list(status: "open")

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

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/disputes/pending \
  -u $OMISE_SECRET_KEY:

<?php

$disputes = OmiseDispute::retrieve('pending');

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const dispute = await omise.disputes.listPending();
console.log(dispute);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

disputes = Omise::Dispute.list(status: "pending")

var resource = Client.Disputes.PendingDisputes;
var pendingDisputes = await resource.GetList(order: Ordering.ReverseChronological);
Console.WriteLine($"pending disputes: {pendingDisputes.Total}");

Request<ScopedList<Dispute>> request = new Dispute.ListRequestBuilder().status(DisputeStatus.Pending).build();
ScopedList<Dispute> disputes = client().sendRequest(request);

System.out.printf("Pending disputes: %d", disputes.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

dispute = omise.Dispute.retrieve(status="pending")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Dispute{}
err := client.Do(result, &operations.ListDisputes{
	State: omise.Pending,
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Dispute.list(status: "pending")

Retrieve a dispute

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

Returns the dispute matching :id.

Example

Retrieve a dispute

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/disputes/dspt_test_5g5ih3pybo7v4wwrbjw \
  -u $OMISE_SECRET_KEY:

<?php

$dispute = OmiseDispute::retrieve('dspt_test_4zgf15h89w8t775kcm8');

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const dispute = await omise.disputes.retrieve('dspt_test_no1t4tnemucod0e51mo');
console.log(dispute);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

dispute = Omise::Dispute.retrieve("dspt_test_4zgf15h89w8t775kcm8")

var disputeId = "dspt_test_58edik07fvhh1i6i3ad";
var dispute = await Client.Disputes.Get(disputeId);
Console.WriteLine($"disputed amount: {dispute.Amount}");

Request<Dispute> request = new Dispute.GetRequestBuilder("dspt_test_4zgf15h89w8t775kcm8").build();
Dispute dispute = client().sendRequest(request);

System.out.printf("Disputed amount: %d", dispute.getAmount());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

dispute = omise.Dispute.retrieve("dspt_test_no1t4tnemucod0e51mo")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Dispute{}
err := client.Do(result, &operations.RetrieveDispute{
	DisputeID: "dspt_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Dispute.retrieve("dspt_test_4zgf15h89w8t775kcm8")

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

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/disputes/dspt_test_5g5ih3pybo7v4wwrbjw \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "message=Unauthorized transaction"

<?php

$dispute = OmiseDispute::retrieve('dspt_test_4zgf15h89w8t775kcm8');
$dispute->update(array(
  'message' => 'Proofs and other information regarding the disputed charge ...'
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const dispute = await omise.disputes.update('dspt_test_no1t4tnemucod0e51mo', {
  message: 'Unauthorized transaction',
});
console.log(dispute);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

dispute = Omise::Dispute.retrieve("dspt_test_4zgf15h89w8t775kcm8")
dispute.update({
  message: "Proofs and other information regarding the disputed charge ..."
})

var dispute = RetrieveOpenDispute();
dispute = await Client.Disputes.Update(dispute.Id, new UpdateDisputeRequest
{
    Message = "Hello, World!"
});

Console.WriteLine($"updated dispute: {dispute.Id}");

Request<Dispute> request = new Dispute.UpdateRequestBuilder("dspt_test_4zgf15h89w8t775kcm8")
        .message("MESSAGE!")
        .build();
Dispute dispute = client().sendRequest(request);

System.out.printf("Updated dispute: %s", dispute.getMessage());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

dispute = omise.Dispute.retrieve("dspt_test_no1t4tnemucod0e51mo")
dispute.update(message="Proofs and other information")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Dispute{}
err := client.Do(result, &operations.UpdateDispute{
	DisputeID: "dspt_test_no1t4tnemucod0e51mo",
	Message:   "Unauthorized transaction",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Dispute.update("dspt_test_4zei9tuoblpoxid97xp", message: "Unauthorized transaction")

Update dispute message and metadata

curl
php
node.js

curl https://api.omise.co/disputes/dspt_test_5g5ih3pybo7v4wwrbjw \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "message=Unauthorized transaction" \
  -d "metadata[order_id]=ORDER-1234" \
  -d "metadata[color]=black"

<?php

$dispute = OmiseDispute::retrieve('dspt_test_6bp9lkvv0rdcymlcc1m');
$dispute->update(array(
    'message'  => 'Unauthorized transaction',
    'metadata' => array(
        'order_id' => 'ORDER_ID',
        'color'    => 'red'
    )
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const dispute = await omise.disputes.update('dspt_test_no1t4tnemucod0e51mo', {
  message: 'Unauthorized transaction',
  metadata:
  {
    order_id: 'order_test_no1t4tnemucod0e51mo',
    color: 'red',
  },
});
console.log(dispute);