Dispute（チャージバック） API

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

Attributes

Name	Type	Description
object	string	固定値`dispute`
id	string	`/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_expandable	チャージバックに関する`CHARGE_ID`。
closed_at	string	チャージバックが終了した ISO 8601に基づくUTC日時（勝訴または敗訴）。
created_at	string	ISO 8601 形式 (`YYYY-MM-DDThh:mm:ssZ`)でチャージバックが作成されたUTC日時。
currency	string	ISO 4217 コードで定義されたチャージバックの通貨。
documents	list	このチャージバックに関しアップロードされた documentsのList（リスト）。
funding_amount	integer	`funding_currency`（`currency` != `funding_currency`の場合）と両替後に加盟店に支払われる金額を[最小通貨単位]（/currency-and-amount）で表したもの。
funding_currency	string	`funding_amount`の通貨
merchant_name	string	チャージバックを実行したサブマーチャントの名前です。注: このフィールドは、加盟店がプラットフォーム向けソリューションを導入している場合にのみ適用されます。プラットフォーム向けソリューションのご利用については、サポートまでお問い合わせください。
merchant_uid	string	チャージバックを実行したサブマーチャントのIDです。注: このフィールドは、加盟店がプラットフォーム向けソリューションを導入している場合にのみ適用されます。プラットフォーム向けソリューションのご利用については、サポートまでお問い合わせください。
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",
  "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"
}

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

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

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

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

Request Parameters

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

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:

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

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

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

Request Parameters

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

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

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

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

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

Request Parameters

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

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

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

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

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

Request Parameters

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

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

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

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

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

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

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

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