> ## Documentation Index > Fetch the complete documentation index at: https://waffo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 出金・残高 API > 自社システムから精算資金を出金し残高を読み取るための、署名付き 5 エンドポイント：consult → create → inquiry の順序、withdrawRequestId による冪等キー、残高照会が返すアカウント、アカウント履歴照会の時間範囲とフィールド。 出金と残高は Portal だけでなく API としても利用できます。Portal 画面、手数料、 明細、自動出金契約については [出金・一括 Payout FAQ](/docs/ja/support/withdrawal-and-batch-payout-faq)、 各残高の意味は [残高・アカウント履歴](/docs/ja/support/balance-and-account-history-faq)、 署名については [認証・署名 FAQ](/docs/ja/support/auth-signature-faq) を参照してください。 ## どのエンドポイントがあり、呼び出すには何が必要ですか？ 5 つすべてが `POST` で、JSON を送受信し、`/api/v1/order/create` とまったく同じ方法で署名します。 | エンドポイント | 用途 | | - | - | | `/api/v1/withdraw/consult` | ドライラン：上限・下限、手数料、受取予定額、受取口座。資金は動きません。 | | `/api/v1/withdraw/create` | 出金注文を作成します。 | | `/api/v1/withdraw/inquiry` | いずれかの ID で出金注文を 1 件読み取ります。 | | `/api/v1/account/balance/inquiry` | 通貨ごとの精算アカウント残高。 | | `/api/v1/account/history/inquiry` | 精算アカウントとReserveアカウントの台帳行。 | 初回呼び出しの多くは 2 つのアクセスルールで引っかかります。**API キーにはスコープがあります**：Payin 専用に発行されたキーではこれらのエンドポイントを呼び出せず、署名が検証される前に `A0004` "Permission denied" で失敗します — 他の場所では正しく署名できているリクエストが `A0004` を返す場合は、出金を含むスコープのキーを Waffo に依頼してください。また、**本文の `merchantId` はキーが解決する MID と一致していなければならず**、一致しない場合は `A0003` になります。`/api/v1/withdraw/inquiry` は例外で、`merchantId` を持ちません — MID はキーから決まり、 別の MID に属する注文は「見つからない」として報告されます。 ## 出金の 3 つの呼び出しはどのように組み合わせますか？ 1. **`consult`** — `currency` と、必要に応じて `amount` を送信します。手数料、受取予定額、 契約上の上限・下限、受取口座が返されるので、確定前に検証できます。 2. **`create`** — 決定した金額と、お客様側で生成した `withdrawRequestId` を送信します。 3. **`inquiry`** — ステータスが最終状態になるまでポーリングするか、`notifyUrl` へのコールバックを待ちます。 `create` は意図的に「完了した出金」ではありません。承認レコードと残高の引き落としは非同期で発生するため、成功した `create` は通常 `IN_PROGRESS` を返します — これは 「受理済み」として扱い、決して「支払済み」として扱わないでください。 ## consult は何を教えてくれますか？amount を省略した場合はどうなりますか？ `amount` を省略すると、consult は「今この瞬間に一度に出金できる最大額はいくらか」に答えます。すなわち **出金可能残高** — 精算アカウントの利用可能残高から、Reserve残高がマイナスの場合はその不足分を差し引いたもの — を、契約の最大額で上限として返します。 | フィールド | 備考 | | - | - | | `amount`、`currency` | 照会した金額、または算出された最大額 | | `beforeAvailableBalance`、`afterAvailableBalance` | この出金の前後の利用可能残高 | | `receiveCurrency`、`expectedReceiveAmount` | 同一通貨：`amount` − `fee`。異なる通貨間：レートがまだ確定していないため、`expectedReceiveAmount` は**一切返されません** | | `feeCurrency`、`fee` | **内枠**で課金されます。金額全体を手数料が食い尽くす場合は拒否されます。異なる通貨間の出金には `feeCurrency` 建ての固定手数料がかかります | | `minWithdrawAmount`、`maxWithdrawAmount` | 出金契約に基づく値。`maxWithdrawAmount` がない場合は上限なし | | `merchantBankAccount` | `bankName`、`bankAccountNo`、`bankAccountName` | 確定した `fxRate` と `actualReceiveAmount` は、注文完了後に `inquiry` で表示されます。 ## create には何が必要で、冪等性はどのように動作しますか？ | フィールド | 必須 | 制約 | | - | - | - | | `withdrawRequestId` | はい | 64 文字以下、MID ごとに一意、冪等キー | | `currency`、`amount` | はい | 金額は文字列、小数点以下最大 2 桁 | | `description` | はい | 128 文字以下 | | `merchantInfo.merchantId` | はい | キーの MID と一致している必要があります。`subMerchantId` は任意 | | `withdrawRequestedAt` | はい | `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` | | `notifyUrl` | はい | `http`/`https`、256 文字以下 | | `bankAccountId` | いいえ | 契約下のどの銀行口座が資金を受け取るか | | `accountNo` | いいえ | 特定の残高アカウント 1 つを対象にします | | `extendInfo` | いいえ | 有効な JSON、128 文字以下、inquiry で返されます | `bankAccountId` を省略すると、契約に紐づく唯一の口座が自動的に使用されます。契約に **複数の口座**がある場合、省略するとパラメータエラーとなり、指定を求められます。`accountNo` は同一通貨で複数の残高アカウントを持つ場合にのみ意味があります — これは別の Waffo エンティティと再契約した後に発生します。 `withdrawRequestId` は MID ごとにスコープされた冪等キーです。同じ `amount` と `currency` で再送すると、**元の**注文の結果が返されます — 2 回目の出金は発生しません。異なる `amount` または `currency` で再送すると、呼び出しは `A0011` "Idempotent param mismatch error" で失敗します。したがって、 タイムアウト時は同一の本文で安全にリトライできます。本当に新しい出金には新しい ID が必要です。 ## ステータスはどのようにポーリングし、各ステータスは何を意味しますか？ `inquiry` には `withdrawRequestId` または `withdrawOrderId` のいずれか一方以上が必要です。どちらもない場合はパラメータエラーです。 両方送信した場合は `withdrawOrderId` が優先され、2 つが一致しない場合は誤った注文を返すのではなく、 呼び出しが失敗します。 | API ステータス | 意味 | | - | - | | `IN_PROGRESS` | まだ最終状態ではない — 未提出、審査中、承認済み、チャネル処理中を含みます | | `SUCCESS` | 完了 | | `FAILURE` | 審査で却下、失敗、クローズ、または銀行による返却が確認された | | `BANK_DISPUTE_NOTIFIED` | 受取銀行が返却を提起した。結果はまだ未確定 | Portal では同じ注文に対してより長く細かいステータス一覧が表示されます — 対応関係は [出金・一括 Payout FAQ](/docs/ja/support/withdrawal-and-batch-payout-faq) にあります。成功時、`inquiry` は `actualReceiveAmount`、`fxRate`（同一通貨の場合は常に `1.00`）、`bankRefId`、 `withdrawCompleteTime` を補完します。失敗時は `failureCode` と `failureReason` を含みます。 ## 残高照会はどのアカウントを返しますか？ **精算アカウント**のみです — 精算通貨ごとに 1 行、契約エンティティごとにまとめられます。 `currency` を渡すと絞り込めます。省略するとすべての通貨が返されます。精算待ち残高はここでは公開されません。 | フィールド | 意味 | | - | - | | `accountNo`、`currency` | アカウント番号はグローバルに一意です。1 通貨につき複数存在する可能性があります | | `totalBalance` / `availableBalance` / `frozenBalance` | アカウント残高、利用可能な金額、チャージバック関連で留保されている金額（`available = total − frozen`） | | `reserveBalance` | その通貨・エンティティのReserve残高。マイナスの場合、その絶対値を `availableBalance` から差し引くと実際に出金できる金額になります | ## アカウント履歴照会はどこまで過去を遡れますか？各行には何が含まれますか？ **このエンドポイントの時刻はすべて UTC です** — 送信する `startTime` / `endTime`（ISO-8601 のローカル日時、例：`2026-08-01T00:00:00`）も、返される `transactionTime`（`...Z`）も同様です。Portal の アカウント履歴は代わりに UTC+8 で表示されます。 * 両方の境界を省略すると**本日分のみ**が返されます。それ以外の場合は両方を送信してください。範囲は **180 日**を超えることができず、**60,000 行**を超える結果になる照会は拒否されます。 * Portal のアカウント履歴と異なり、このエンドポイントは精算台帳とReserve台帳の**両方**を対象とします。`accountType` = `MERCHANT_SETTLEMENT` または `MERCHANT_RESERVE` でフィルターし、省略すると両方が 返されます。`currency` と `accountNo` でさらに絞り込めます。保有していないアカウントを指定したフィルターは、空のリストではなくアカウントが見つからないエラーを返します。 各行には `accountNo`、`accountType`、`currency`、`amount`、`accountDirection` （`CREDIT` / `DEBIT`）、`newBalance`（その変動直後の残高）、`transactionTime`、 `businessId`（関連する業務注文）、`businessType` — `SETTLEMENT`、 `WITHDRAWAL`、`RESERVE_WITHHOLDING`、`RESERVE_RELEASING`、`RESERVE_ADJUSTMENT`、`ADJUSTMENT` などのコードで、大文字小文字を区別せずに照合するのが最善です — が含まれます。それぞれの意味は [残高・アカウント履歴](/docs/ja/support/balance-and-account-history-faq) にあります。 ## どのエラーを明示的に処理すべきですか？ | コード | 発生する場面 | | - | - | | `A0003` / `A0004` | パラメータ検証に失敗した（`merchantId` がキーと一致しない場合を含む）/ キーのスコープがこのエンドポイントを含んでいない | | `A0007` / `A0008` | 出金通貨がお客様には対応していない / 金額が契約の範囲外 | | `A0010` / `A0012` | 契約上許可されていない / 残高不足 | | `A0011` | 同じ `withdrawRequestId` を異なるパラメータで再送した | | `E0001` | ステータス不明 — 最終状態になるまで `inquiry` をポーリングし続けてください。2 件目の注文を作成しないでください | *** まだ解決しませんか？`withdrawRequestId` または `withdrawOrderId` と呼び出しのタイムスタンプを添えて、[サポートにお問い合わせください](mailto:support@waffo.com)。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.