> ## 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.

# 残高 API リファレンス (v2)

> Hello Clever の加盟店アカウントに設定されたすべての通貨について、多通貨の残高の詳細を照会し、残高取引の履歴全体を取得します。

v2 残高 API では、Hello Clever アカウントに設定されたすべての通貨について、現在の残高の状況を照会できます。5つの異なる残高種別を確認して、いくら利用できるか、移動中か、確保されているか、出金できるかを正確に把握でき、残高を変動させたすべての取引の日付付きの履歴も取得できます。

## 残高の種別

| 残高の種別                     | 説明                                                                 |
| ------------------------- | ------------------------------------------------------------------ |
| `available_balance`       | すべての取引に利用できる残高。                                                    |
| `incoming_balance`        | 成功した決済のうち、第三者の提供事業者がまだ資金を精算していないもの（カード決済の取引など）。                    |
| `outgoing_balance`        | 現在移動中の資金で、返金、異議申立て、Payout を処理するために利用可能残高から差し引かれるのを待っているもの。         |
| `rolling_reserve_balance` | 加盟店残高に保持される変動する予備の金額。必須ではありません。有効にするには Hello Clever のサポートへご連絡ください。 |
| `withdrawable_balance`    | 出金できる金額。ローリングリザーブは含みません。                                           |

***

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

<Badge color="green">GET</Badge> `/v2/balances/detail`

指定した通貨について、アカウントの現在の残高の内訳を返します。

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

<ParamField query="currency" type="string" required>
  ISO 4217 の通貨コード（例：`AUD`、`VND`、`MYR`）。Hello Clever アカウントに設定されている通貨である必要があります。
</ParamField>

### レスポンスの項目

<ResponseField name="currency" type="string">
  残高の通貨。
</ResponseField>

<ResponseField name="available_balance" type="number">
  取引に利用できる残高。
</ResponseField>

<ResponseField name="incoming_balance" type="number">
  受け取ったが、まだ第三者の提供事業者によって精算されていない資金。
</ResponseField>

<ResponseField name="outgoing_balance" type="number">
  出金の処理（返金、Payout、異議申立て）のために移動中の資金。
</ResponseField>

<ResponseField name="rolling_reserve_balance" type="number">
  確保されている残高の金額。ローリングリザーブが設定されていない場合は `0` を返します。
</ResponseField>

<ResponseField name="withdrawable_balance" type="number">
  出金できる金額。`available_balance` から `rolling_reserve_balance` を差し引いた額です。
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/balances/detail?currency=AUD' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "currency": "AUD",
    "available_balance": 125000.00,
    "incoming_balance": 5000.00,
    "outgoing_balance": 2500.00,
    "rolling_reserve_balance": 10000.00,
    "withdrawable_balance": 115000.00
  }
  ```
</CodeGroup>

<Note>
  複数の通貨の残高を照会するには、通貨ごとにこのエンドポイントを呼び出してください。各 `app-id` は1つの通貨に対応します。複数の通貨を扱う場合は、通貨ごとに個別の `app-id` と `secret-key` を持つことになります。
</Note>

***

<a id="get-balance-history" />

## 残高履歴を取得する

<Badge color="green">GET</Badge> `/v2/balances/history`

指定した期間における残高取引の詳細な履歴を取得します。アカウントに設定された**すべての通貨**にわたり、入金された決済、Payout、精算、返金、トップアップ、出金、異議申立て、キャッシュバックの支払、アカウント間送金を含む、すべての残高の変動が含まれます。

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

<ParamField query="from_date" type="date-time" required>
  期間の開始日時（形式は `YYYY-MM-DDThh:mm:ssZ`）。UTC として解釈されます。
</ParamField>

<ParamField query="to_date" type="date-time" required>
  期間の終了日時（形式は `YYYY-MM-DDThh:mm:ssZ`）。UTC として解釈されます。
</ParamField>

<ParamField query="cursor" type="string">
  ページ分割のカーソル。前のレスポンスの `next_cursor` の値を使います。最初のページを取得する場合はこのパラメーターを省略してください。
</ParamField>

<ParamField query="size" type="integer" default="20">
  1 ページあたりに返す件数。
</ParamField>

### レスポンスの項目

<ResponseField name="from_date" type="string">
  照会した期間の開始日時。
</ResponseField>

<ResponseField name="to_date" type="string">
  照会した期間の終了日時。
</ResponseField>

<ResponseField name="account_type" type="string">
  リクエスト元のアカウントの残高モデル。`aggregated` または `dedicated` です。各モデルの意味は[残高とアカウントの管理](/ja/portal/balances)を参照してください。
</ResponseField>

<ResponseField name="size" type="integer">
  このページで返された件数。
</ResponseField>

<ResponseField name="next_cursor" type="string">
  次のページを取得するために `cursor` のクエリパラメーターとして渡すカーソル。残りの記録がない場合は `null` になります。
</ResponseField>

<ResponseField name="has_more" type="boolean">
  このページの後にさらに記録があるかどうか。
</ResponseField>

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

  <Expandable title="properties">
    <ResponseField name="id" type="string">Balance ID：この残高の記録の一意の識別子。</ResponseField>
    <ResponseField name="amount" type="number">手数料差引後の取引の純額。</ResponseField>

    <ResponseField name="request_type" type="string">
      残高の変動の方向。`money_in`（増加）または `money_out`（減少）です。
    </ResponseField>

    <ResponseField name="transaction_type" type="string">
      残高の変動の原因。`payment`、`payout`、`settlement`、`refund`、`topup`、`withdrawal`、`dispute`、`dispute_fee`、`cashback_payout`、`transfer_in`、`transfer_out` のいずれかです。
    </ResponseField>

    <ResponseField name="currency" type="string">この記録の通貨。</ResponseField>
    <ResponseField name="payment_method" type="string">使用された決済手段（例：`bsb`）。</ResponseField>

    <ResponseField name="status" type="string">
      残高の流れの現在のステータス。`waiting`、`done`、`failed` のいずれかです。
    </ResponseField>

    <ResponseField name="reference_id" type="string">元の取引の参照コード。</ResponseField>

    <ResponseField name="balance_detail" type="object">
      この記録の総額、純額、手数料の内訳。

      <Expandable title="properties">
        <ResponseField name="outgoing" type="number">手数料を除いた取引金額。</ResponseField>
        <ResponseField name="total" type="number">手数料差引後に請求された取引金額。</ResponseField>
        <ResponseField name="fees" type="number">この取引に課された手数料。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string">残高取引が作成された日時 (UTC)。</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/balances/history?from_date=2026-01-01T00:00:00Z&to_date=2026-01-31T00:00:00Z' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "from_date": "2026-01-01T00:00:00Z",
    "to_date": "2026-01-31T00:00:00Z",
    "account_type": "aggregated",
    "size": 20,
    "next_cursor": "eyJpZCI6ImJsX3BpX3duNFRXaGxYQnJaSyJ9",
    "has_more": true,
    "records": [
      {
        "id": "bl_pi_wn4TWhlXBrZK",
        "amount": 202.66,
        "request_type": "money_out",
        "transaction_type": "settlement",
        "currency": "AUD",
        "payment_method": "bsb",
        "status": "done",
        "reference_id": "BAL_cqxDHqDOSs8=--4",
        "balance_detail": {
          "outgoing": 205,
          "total": 202.66,
          "fees": 2.34
        },
        "created_at": "2026-01-01T00:00:00.000+0000"
      }
    ]
  }
  ```
</CodeGroup>

<a id="status-labels-in-the-portal" />

#### Portal でのステータスのラベル

このエンドポイントが返す `status` の値は、Merchant Portal に表示されるラベルとすべて一致するわけではありません。

| API の値    | Portal のラベル    |
| --------- | -------------- |
| `waiting` | **Processing** |
| `done`    | **Done**       |
| `failed`  | **Failed**     |

<Note>
  これらのステータスを Portal と並べて自社のインターフェースに表示する場合、または同僚が[残高の画面](/ja/portal/balances#取引テーブル)で見ている内容と API のレスポンスを照合する場合は、`waiting` を **Processing** に対応づけてください。
</Note>

### 結果のページ分割

このエンドポイントは**カーソルベースのページ分割**を使用します。結果全体をたどる手順は次のとおりです。

<Steps>
  <Step title="最初のページを取得する">
    `from_date` と `to_date` のみを指定し、`cursor` は省略してエンドポイントを呼び出します。
  </Step>

  <Step title="`has_more` を確認する">
    `has_more` が `false` であれば、すべての記録を取得済みで `next_cursor` は `null` です。ここで終了します。
  </Step>

  <Step title="次のページを取得する">
    前のレスポンスの `next_cursor` の値を `cursor` のパラメーターとして渡します。`from_date`、`to_date`、`size` は変更しないでください。`has_more` が `false` になるまで繰り返します。
  </Step>
</Steps>

<Warning>
  `next_cursor` は不透明なトークンとして扱ってください。その内容は実装の詳細であり、変わる可能性があります。パースしたり、自分で構築したり、永続的なブックマークとして保存したりしないでください。
</Warning>

<a id="migrating-from-v1-balance-history" />

### v1 の残高履歴からの移行

現在 `GET /v1/balances/history` を呼び出している場合、次の違いにご注意ください。

|           | v1                      | v2                                                           |
| --------- | ----------------------- | ------------------------------------------------------------ |
| 対応通貨      | AUD のみ                  | アカウントに設定されたすべての通貨                                            |
| ページ分割     | `page` と `per_page` の番号 | `cursor` と `size`（不透明なカーソル）                                  |
| 日付のパラメーター | 日付 (`2026-01-01`)       | 日時 (`2026-01-01T00:00:00Z`)、UTC                              |
| 記録の一覧の項目名 | `data`                  | `records`                                                    |
| 金額の表現     | 符号付きで、負の値が出金            | 符号なしの `amount` と、`money_in` または `money_out` の `request_type` |
| 残高の累計     | 記録ごとに `balance_after`   | 返されません                                                       |
| 手数料の内訳    | 返されません                  | `balance_detail.outgoing` / `total` / `fees`                 |

<Warning>
  金額の表現はバージョン間で異なります。v1 では返金が負の `amount` として現れますが、v2 では同じ返金が**正**の `amount` と `request_type: "money_out"` になります。`request_type` を確認せずに v2 の金額を合計すると、純額を過大に見積もることになります。
</Warning>

## 残高を理解する

Payout や返金を開始する前に、このエンドポイントでアカウントの健全性を確認してください。

* Payout を作成する前に `available_balance` を確認し、十分な資金があることを確かめてください。
* 今後の精算を見込むために `incoming_balance` をモニタリングしてください。
* 保留中の処理に現在充てられている資金を把握するために `outgoing_balance` を追跡してください。
* `rolling_reserve_balance` の設定や調整については [support@helloclever.co](mailto:support@helloclever.co) へお問い合わせください。


## Related topics

- [AUD 残高 API リファレンス](/ja/api/v1/balance.md)
- [多通貨 Payout API リファレンス (v2)](/ja/api/v2/payout.md)
- [多通貨 Payin API リファレンス (v2)](/ja/api/v2/payin.md)