> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rc.cleverhub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# AUD 残高 API リファレンス

> Hello Clever の v1 API を通じて、AUD のアカウント残高（利用可能、入金予定、出金予定、ローリングリザーブ、出金可能）を照会し、残高履歴を取得します。

残高のエンドポイントにより、Hello Clever アカウントの資金をリアルタイムに把握できます。残高詳細のエンドポイントですべての残高種別の現在の状態を確認し、残高履歴のエンドポイントで指定した期間における残高の変動（受け取った決済、発行した返金、トップアップを含む）を監査できます。

<Note>
  これらのエンドポイントは **AUD の残高のみ**に対応しています。他の通貨の残高や残高履歴を照会するには、アカウントに設定されたすべての通貨を扱う [v2 残高 API](/ja/api/v2/balance) を使ってください。
</Note>

***

## 残高の詳細を取得する

<Note>
  `GET /v1/balances/detail`
</Note>

アカウント内のすべての残高種別のリアルタイムな内訳を取得します。

### 残高の種別

| 残高の種別                     | 説明                                                            |
| ------------------------- | ------------------------------------------------------------- |
| `available_balance`       | 取引に直ちに利用できる資金。                                                |
| `incoming_balance`        | 成功した決済から計上されたが、まだ第三者の提供事業者（カード処理会社など）によって精算されていない資金。          |
| `outgoing_balance`        | 返金、異議申立て、Payout などの保留中の処理のために確保された資金。                         |
| `rolling_reserve_balance` | チャージバックや債務に備えた安全余裕として保持される予備資金。この機能を有効にするにはテクニカルサポートへご連絡ください。 |
| `withdrawable_balance`    | 利用可能残高のうち出金できる部分（ローリングリザーブの資金を除きます）。                          |

### レスポンスの項目

<ResponseField name="currency" type="string">
  通貨コード (`AUD`)。
</ResponseField>

<ResponseField name="available_balance" type="number">
  あらゆる取引に直ちに利用できる資金（AUD）。
</ResponseField>

<ResponseField name="incoming_balance" type="number">
  成功した決済から計上待ちの資金（AUD）。
</ResponseField>

<ResponseField name="outgoing_balance" type="number">
  保留中の返金、異議申立て、Payout のために確保された資金（AUD）。
</ResponseField>

<ResponseField name="rolling_reserve_balance" type="number">
  安全余裕として保持される予備資金（AUD）。
</ResponseField>

<ResponseField name="withdrawable_balance" type="number">
  ローリングリザーブの資金を除いた利用可能残高（AUD）。
</ResponseField>

<ResponseField name="retrieved_at" type="string">
  残高のスナップショットを取得した日時（ISO 8601）。
</ResponseField>

### コードの例

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api-merchant.helloclever.co/api/v1/balances/detail \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```
</CodeGroup>

<CodeGroup>
  ```json 200 - Success theme={null}
  {
    "currency": "AUD",
    "available_balance": 12450.75,
    "incoming_balance": 3200.00,
    "outgoing_balance": 500.00,
    "rolling_reserve_balance": 1000.00,
    "withdrawable_balance": 11450.75,
    "retrieved_at": "2026-04-17T10:00:00Z"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid app-id or secret-key."
  }
  ```
</CodeGroup>

***

## 残高履歴を取得する

<Note>
  `GET /v1/balances/history`
</Note>

指定した期間内のすべての残高の変動の詳細な履歴を取得します。入金された決済、返金、トップアップ、Payout、そしてアカウント残高に影響するその他の活動が含まれます。

<Tip>
  多通貨の残高履歴には、代わりに [`GET /v2/balances/history`](/ja/api/v2/balance#get-balance-history) を使ってください。アカウントのすべての通貨にわたる記録を返し、取引ごとの手数料の内訳も含みます。パラメーターとレスポンスの違いは[v1 残高履歴からの移行](/ja/api/v2/balance#migrating-from-v1-balance-history)を参照してください。
</Tip>

### クエリのパラメーター

<ParamField query="from_date" type="string" required>
  期間の開始日（ISO 8601 形式。例：`2026-01-01`）。
</ParamField>

<ParamField query="to_date" type="string" required>
  期間の終了日（ISO 8601 形式。例：`2026-04-17`）。
</ParamField>

<ParamField query="page" type="number" default="1">
  ページ分割された結果のページ番号。
</ParamField>

<ParamField query="per_page" type="number" default="20">
  1 ページあたりの件数。
</ParamField>

### レスポンスの項目

<ResponseField name="data" type="array">
  残高履歴の項目の一覧。

  <Expandable title="properties">
    <ResponseField name="id" type="string">残高履歴の項目の一意の識別子。</ResponseField>

    <ResponseField name="type" type="string">
      残高の変動の種別（例：`payment_received`、`refund_issued`、`top_up`、`payout`）。
    </ResponseField>

    <ResponseField name="amount" type="number">
      AUD での残高の変動額。正の値は入金、負の値は出金を示します。
    </ResponseField>

    <ResponseField name="balance_after" type="number">
      この取引の後の利用可能残高（AUD）。
    </ResponseField>

    <ResponseField name="reference_id" type="string">
      関連する取引の識別子（決済リクエスト ID や Payout ID など）。
    </ResponseField>

    <ResponseField name="description" type="string">
      残高の変動について人が読める説明。
    </ResponseField>

    <ResponseField name="created_at" type="string">
      残高の変動が発生した日時（ISO 8601）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  クエリに一致する残高履歴の項目の総数。
</ResponseField>

<ResponseField name="page" type="number">
  現在のページ番号。
</ResponseField>

### コードの例

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api-merchant.helloclever.co/api/v1/balances/history?from_date=2026-04-01&to_date=2026-04-17&page=1' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```
</CodeGroup>

<CodeGroup>
  ```json 200 - Success theme={null}
  {
    "data": [
      {
        "id": "bh_entry_001",
        "type": "payment_received",
        "amount": 99.95,
        "balance_after": 12450.75,
        "reference_id": "pr_abc123",
        "description": "Payment received for Order #1042",
        "created_at": "2026-04-17T10:15:00Z"
      },
      {
        "id": "bh_entry_002",
        "type": "refund_issued",
        "amount": -250.00,
        "balance_after": 12200.75,
        "reference_id": "ref_jkl012",
        "description": "Refund issued for Invoice #5021",
        "created_at": "2026-04-17T11:00:00Z"
      }
    ],
    "total": 2,
    "page": 1
  }
  ```

  ```json 422 - Unprocessable Entity theme={null}
  {
    "error": "UnprocessableEntity",
    "message": "from_date and to_date are required."
  }
  ```
</CodeGroup>


## Related topics

- [残高 API リファレンス (v2)](/ja/api/v2/balance.md)
- [入金シミュレーション API リファレンス](/ja/api/v1/simulate-deposit.md)
- [多通貨 Payout API リファレンス (v2)](/ja/api/v2/payout.md)