返金一覧の取得

GEThttps://api.omise.co/refunds

すべての課金にわたる返金のページネーションされた一覧を取得します。フィルタリング機能付きで、作成日順にソートされた返金を返します。

---

リクエストパラメータ

推奨 - 3項目推奨パラメータ

▼

`limit`INTEGER(optional)

1ページあたりに返す返金の数。

Example:20

Constraints:最小値: 1, 最大値: 100

Default:20

`offset`INTEGER(optional)

ページネーションのためにスキップする返金の数。limitと併用してページ間を移動します。

Example:0

Default:0

`order`STRING(optional)

作成日によるソート順。

Example:"chronological"

Values:chronological, reverse_chronological

Default:"chronological"

追加 - 2項目追加パラメータ

▼

---

レスポンス

200

一覧取得成功

返金データ配列とページネーションメタデータを含むリストオブジェクトを返します。

リストレスポンスの内容:

• object - 値は "list"
• data - 返金オブジェクトの配列
• total - フィルタに一致する返金の総数
• limit - 1ページあたりの項目数
• offset - 現在のページネーションオフセット
• order - 適用されたソート順
• from / to - 適用された日付範囲

各返金オブジェクトの内容:

• object - 値は "refund"
• id - 返金識別子（rfnd_*）
• livemode - 本番モードまたはテストモード
• location - 返金オブジェクトへのAPIパス
• acquirer_reference_number - カードネットワークに送信された参照番号
• amount - 最小通貨単位での返金額
• approval_code - 承認済み取引の参照番号
• capture - キャプチャ参照
• charge - 関連する課金ID（展開可能）
• currency - ISO 4217の3文字通貨コード
• funding_amount - 決済通貨での金額
• funding_currency - 決済通貨コード
• merchant_name - サブマーチャント名（Payfacのみ）
• merchant_uid - サブマーチャントID（Payfacのみ）
• metadata - 返金に添付されたカスタムメタデータ
• status - 現在の返金ステータス（pending、successful、failed）
• terminal - 元の販売時点情報
• transaction - 関連するトランザクションID（展開可能）
• voided - 返金がボイドとして処理されたかどうか
• created_at - 返金作成タイムスタンプ（ISO 8601）

400

不正なリクエスト

無効なパラメータが指定されました。

よくある原因:

• 無効な日付形式（ISO 8601である必要があります）
• limitが範囲外（1〜100である必要があります）
• 無効なoffset値

401

認証エラー

認証に失敗しました。APIキーが無効または不足しています。

よくある原因:

• Authorizationヘッダーがない
• シークレットキーが無効
• シークレットキーの代わりにパブリックキーを使用

404

見つかりません

リクエストされたリソースが見つかりませんでした。

よくある原因:

• 無効なAPIエンドポイントURL
• 不正なURLパス

5xx

サーバーエラー

サーバー側のエラーが発生しました。これらはまれですが、適切に処理する必要があります。

対処方法:

• 指数バックオフでリクエストを再試行
• status.omise.coでサービス障害を確認
• 詳細なガイダンスはエラー処理を参照

---

コードサンプル

cURL

curl "https://api.omise.co/refunds?limit=20&offset=0" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

refunds = Omise::Refund.list(limit: 20, offset: 0)

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

refunds = omise.Refund.list(limit=20, offset=0)

Node.js

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

const refunds = await omise.refunds.list({
  limit: 20,
  offset: 0
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$refunds = OmiseRefund::retrieve(array(
    'limit' => 20,
    'offset' => 0
));

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

ScopedList<Refund> refunds = client.refunds().list()
    .limit(20)
    .offset(0)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var refunds = await client.Refunds.GetList(new ListOptions {
    Limit = 20,
    Offset = 0
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

refunds, _ := client.ListRefunds(&operations.ListRefunds{
    List: operations.List{
        Limit:  20,
        Offset: 0,
    },
})

---

エラーコードと結果コード

一般的な使用パターン

パターン	説明	例
基本的なページネーション	ページを順番に取得	limit=20&offset=0、次にoffset=20、など
日付範囲フィルタ	作成日でフィルタリング	from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z
新しい順	最新の返金を先に表示	order=reverse_chronological

ページネーションの計算

フィールド	計算方法	用途
次のページ	offset + limit	次の結果セットを取得
前のページ	offset - limit（最小0）	前のページに戻る
続きがあるか	offset + limit < total	さらにページがあるか確認
ページ番号	(offset / limit) + 1	現在のページ番号

返金ステータスコード

ステータス	説明
pending	返金処理中
successful	返金が正常に完了
failed	返金に失敗（まれ）

---

🔑API認証情報

▼

試してみる

推奨 - 3項目

▼

追加 - 2項目

▼

あなたのIP: ...読み込み中...