Hello Clever Developer Docs

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

残高の種別

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

残高の詳細を取得する

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

クエリのパラメーター

string

必須

ISO 4217 の通貨コード（例：AUD、VND、MYR）。Hello Clever アカウントに設定されている通貨である必要があります。

レスポンスの項目

string

残高の通貨。

number

取引に利用できる残高。

number

受け取ったが、まだ第三者の提供事業者によって精算されていない資金。

number

出金の処理（返金、Payout、異議申立て）のために移動中の資金。

number

確保されている残高の金額。ローリングリザーブが設定されていない場合は 0 を返します。

number

出金できる金額。available_balance から rolling_reserve_balance を差し引いた額です。

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'

{
  "currency": "AUD",
  "available_balance": 125000.00,
  "incoming_balance": 5000.00,
  "outgoing_balance": 2500.00,
  "rolling_reserve_balance": 10000.00,
  "withdrawable_balance": 115000.00
}

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

残高履歴を取得する

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

クエリのパラメーター

date-time

必須

期間の開始日時（形式は YYYY-MM-DDThh:mm:ssZ）。UTC として解釈されます。

date-time

必須

期間の終了日時（形式は YYYY-MM-DDThh:mm:ssZ）。UTC として解釈されます。

string

ページ分割のカーソル。前のレスポンスの next_cursor の値を使います。最初のページを取得する場合はこのパラメーターを省略してください。

integer

デフォルト:"20"

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

レスポンスの項目

string

照会した期間の開始日時。

string

照会した期間の終了日時。

string

リクエスト元のアカウントの残高モデル。aggregated または dedicated です。各モデルの意味は残高とアカウントの管理を参照してください。

integer

このページで返された件数。

string

次のページを取得するために cursor のクエリパラメーターとして渡すカーソル。残りの記録がない場合は null になります。

boolean

このページの後にさらに記録があるかどうか。

array

残高履歴の項目の一覧。

表示 properties

string

Balance ID：この残高の記録の一意の識別子。

number

手数料差引後の取引の純額。

string

残高の変動の方向。money_in（増加）または money_out（減少）です。

string

残高の変動の原因。payment、payout、settlement、refund、topup、withdrawal、dispute、dispute_fee、cashback_payout、transfer_in、transfer_out のいずれかです。

string

この記録の通貨。

string

使用された決済手段（例：bsb）。

string

残高の流れの現在のステータス。waiting、done、failed のいずれかです。

string

元の取引の参照コード。

object

この記録の総額、純額、手数料の内訳。

表示 properties

number

手数料を除いた取引金額。

number

手数料差引後に請求された取引金額。

number

この取引に課された手数料。

string

残高取引が作成された日時 (UTC)。

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'

{
  "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"
    }
  ]
}

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

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

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

これらのステータスを Portal と並べて自社のインターフェースに表示する場合、または同僚が残高の画面で見ている内容と API のレスポンスを照合する場合は、waiting を Processing に対応づけてください。

結果のページ分割

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

最初のページを取得する

from_date と to_date のみを指定し、cursor は省略してエンドポイントを呼び出します。

`has_more` を確認する

has_more が false であれば、すべての記録を取得済みで next_cursor は null です。ここで終了します。

次のページを取得する

前のレスポンスの next_cursor の値を cursor のパラメーターとして渡します。from_date、to_date、size は変更しないでください。has_more が false になるまで繰り返します。

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

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`

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

残高を理解する

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

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

基本

Payment Gateway (AUD)

Multi-Currency Payment API

Payment Gateway 3

Card API

Cashback API

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

残高の種別

残高の詳細を取得する

クエリのパラメーター

レスポンスの項目

残高履歴を取得する

クエリのパラメーター

レスポンスの項目

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

結果のページ分割

v1 の残高履歴からの移行

残高を理解する

​残高の種別

​残高の詳細を取得する

​クエリのパラメーター

​レスポンスの項目

​残高履歴を取得する

​クエリのパラメーター

​レスポンスの項目

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

​結果のページ分割

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

​残高を理解する

残高の種別

残高の詳細を取得する

クエリのパラメーター

レスポンスの項目

残高履歴を取得する

クエリのパラメーター

レスポンスの項目

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

結果のページ分割

v1 の残高履歴からの移行

残高を理解する