Dispute（チャージバック） API

Dispute（チャージバック） APIからチャージバックを検索、更新できます。顧客が請求額に疑義がある場合、カード会社を通して Disputeを申し立てることができます。チャージバックの解決に役立つ文書類は、Document APIを通じてアップロードすることができます。チャージバックは、open（開始）pending（保留中）, won（勝訴）, もしくは lost（敗訴）いずれかのステータスとなります。

Attributes

Name	Type	Description
object	string	固定値`dispute`
id	object_id	`/cust(_test)?_[0-9a-z]+/`に一致する`DISPUTE_ID`。
livemode	boolean	本番モード (`true`) あるいはテストモード(`false`) チャージバックか。
location	string	現在の`dispute`オブジェクトを取得するためのAPIパス。
admin_message	string	チャージバックに関連し管理者からメッセージが追加されました。
amount	integer	smallest currency unit（最小の通貨単位）でのチャージバックの金額
charge	object_id	チャージバックに関する`CHARGE_ID`。
closed_at	datetime	チャージバックが終了した ISO 8601に基づくUTC日時（勝訴または敗訴）。
created_at	datetime	ISO 8601 形式 (`YYYY-MM-DDThh:mm:ssZ`)でチャージバックが作成されたUTC日時。
currency	currency	ISO 4217 コードで定義されたチャージバックの通貨。
documents	list	このチャージバックに関しアップロードされた documentsのList（リスト）。
funding_amount	integer	`funding_currency`（`currency` != `funding_currency`の場合）と両替後に加盟店に支払われる金額を[最小通貨単位]（/currency-and-amount）で表したもの。
funding_currency	currency	`funding_amount`の通貨
message	string	チャージバックに対する説明。
metadata	object	メタデータをカスタムする (例 `{"customer-id": 42}`) チャージバック。
reason_code	string	チャージバックコード。
reason_message	string	チャージバックコードに関するチャージバックのメッセージ。
status	string	チャージバックのステータス。`open`, `pending`, `won` または `lost` のいずれか。（注意:`won`と`lost`の紛争は `/disputes/closed`エンドポイントを使って取得できます）。
transactions	array	このチャージバックに関連した取引。

Example

JSON Response

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

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:

チャージバック情報の取得

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

Dispute IDで指定したチャージバックの情報を取得します。

Example

チャージバック情報の取得

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');

omise.disputes.retrieve("dspt_test_4zgf15h89w8t775kcm8", function(err, resp) {
  /* Response. */
});

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

dispute, retrieve := &omise.Dispute{}, &operations.RetrieveDispute{
	DisputeID: "dspt_test_4zgf15h89w8t775kcm8",
}

if e := client.Do(dispute, retrieve); e != nil {
	log.Fatalln(e)
}

log.Printf("dispute: %#v\n", dispute)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Dispute.retrieve("dspt_test_4zgf15h89w8t775kcm8")

チャージバック情報の更新

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

Dispute IDで指定したチャージバックの情報を更新し、そのデータを取得します。

Request Parameters

Name	Type	Description
message	string	(任意) チャージバックに対する説明。
metadata	object	(任意) メタデータをカスタムする (例 `{"customer-id": 42}`) チャージバック。

Example

チャージバック情報の更新

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

omise.disputes.update("dspt_test_4zgf15h89w8t775kcm8", {
  "message": "Unauthorized transaction"
}, function(err, resp) {
  /* Response. */
});

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

dispute, update := &omise.Dispute{}, &operations.UpdateDispute{
	DisputeID: "dspt_test_4zgf15h89w8t775kcm8",
	Message:   "Unauthorized transaction",
}

if e := client.Do(dispute, update); e != nil {
	log.Fatalln(e)
}

log.Printf("updated dispute: %#v\n", dispute)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

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

Update dispute metadata

curl
php

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'
    )
));

チャージバックリストの取得

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

disputeに属するすべてのお客様のアカウントオブジェクトの list を返します。

Request Parameters

Name	Type	Description
from	datetime	(任意, default: `1970-01-01T00:00:00Z`) ISO 8601 形式(`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日時。
limit	integer	(任意, default: 20, maximum: 100) 返されるレコードの数。
offset	integer	(任意, default: 0) 返される最初のレコードのオフセット(先頭からスキップするレコードの数)。
order	string	(任意, default: `chronological`) listのオーダーが`chronological` (古い順) or `reverse_chronological` (新しい順)で返されます。エントリがない場合は `null`となります。
to	datetime	(任意, default: current UTC datetime) ISO 8601形式 (`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日付と時刻。

Example

チャージバックリストの取得

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

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

<?php

$disputes = OmiseDispute::retrieve();

omise.disputes.list(function(err, resp) {
  /* Response. */
});

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

disputes, list := &omise.DisputeList{}, &operations.ListDisputes{}
if e := client.Do(disputes, list); e != nil {
	log.Fatalln(e)
}

log.Printf("disputes: %#v\n", disputes)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Dispute.list

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

- 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:

Closes the dispute matching `:id`. Only for test mode.

- 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	(任意) 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"

チャージバックリスト（status: 'won' or 'lost'）の取得

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

チャージバックオブジェクトのステータスが 'won' または 'lost' のリストを取得。ここで返されるリストは、チャージバックの処理が 'won' または 'lost' で終了しているデータです。

Request Parameters

Name	Type	Description
from	datetime	(任意, default: `1970-01-01T00:00:00Z`) ISO 8601 形式(`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日時。
limit	integer	(任意, default: 20, maximum: 100) 返されるレコードの数。
offset	integer	(任意, default: 0) 返される最初のレコードのオフセット(先頭からスキップするレコードの数)。
order	string	(任意, default: `chronological`) listのオーダーが`chronological` (古い順) or `reverse_chronological` (新しい順)で返されます。エントリがない場合は `null`となります。
to	datetime	(任意, default: current UTC datetime) ISO 8601形式 (`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日付と時刻。

Example

チャージバックリスト（status: 'won' or 'lost'）の取得

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');

omise.disputes.listClosed(function(err, resp) {
  /* Response. */
});

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

disputes, list := &omise.DisputeList{}, &operations.ListDisputes{
	State: omise.Open,
}

if e := client.Do(disputes, list); e != nil {
	log.Fatalln(e)
}

log.Println("# of open disputes:", len(disputes.Data))

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

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

チャージバックリスト（status: 'open'）の取得

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

チャージバックオブジェクトのステータスが open のリストを取得。

Request Parameters

Name	Type	Description
from	datetime	(任意, default: `1970-01-01T00:00:00Z`) ISO 8601 形式(`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日時。
limit	integer	(任意, default: 20, maximum: 100) 返されるレコードの数。
offset	integer	(任意, default: 0) 返される最初のレコードのオフセット(先頭からスキップするレコードの数)。
order	string	(任意, default: `chronological`) listのオーダーが`chronological` (古い順) or `reverse_chronological` (新しい順)で返されます。エントリがない場合は `null`となります。
to	datetime	(任意, default: current UTC datetime) ISO 8601形式 (`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日付と時刻。

Example

チャージバックリスト（status: 'open'）の取得

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');

omise.disputes.listOpen(function(err, resp) {
  /* Response. */
});

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

disputes, list := &omise.DisputeList{}, &operations.ListDisputes{
	State: omise.Open,
}

if e := client.Do(disputes, list); e != nil {
	log.Fatalln(e)
}

log.Printf("open disputes: %#v\n", disputes)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

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

チャージバックリスト（status: 'pending'）の取得

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

チャージバックオブジェクトのステータスが pending のリストを取得。

Request Parameters

Name	Type	Description
from	datetime	(任意, default: `1970-01-01T00:00:00Z`) ISO 8601 形式(`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日時。
limit	integer	(任意, default: 20, maximum: 100) 返されるレコードの数。
offset	integer	(任意, default: 0) 返される最初のレコードのオフセット(先頭からスキップするレコードの数)。
order	string	(任意, default: `chronological`) listのオーダーが`chronological` (古い順) or `reverse_chronological` (新しい順)で返されます。エントリがない場合は `null`となります。
to	datetime	(任意, default: current UTC datetime) ISO 8601形式 (`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日付と時刻。

Example

チャージバックリスト（status: 'pending'）の取得

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');

omise.disputes.listPending(function(err, resp) {
  /* Response. */
});

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

disputes, list := &omise.DisputeList{}, &operations.ListDisputes{
	State: omise.Pending,
}

if e := client.Do(disputes, list); e != nil {
	log.Fatalln(e)
}

log.Printf("pending disputes; %#v\n", disputes)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

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