どのエンドポイントがあり、呼び出すには何が必要ですか？
5 つすべてがPOST で、JSON を送受信し、/api/v1/order/create とまったく同じ方法で署名します。
初回呼び出しの多くは 2 つのアクセスルールで引っかかります。API キーにはスコープがあります：Payin 専用に発行されたキーではこれらのエンドポイントを呼び出せず、署名が検証される前に
A0004 “Permission denied” で失敗します —
他の場所では正しく署名できているリクエストが A0004 を返す場合は、出金を含むスコープのキーを Waffo に依頼してください。また、本文の merchantId はキーが解決する MID と一致していなければならず、一致しない場合は
A0003 になります。/api/v1/withdraw/inquiry は例外で、merchantId を持ちません — MID はキーから決まり、
別の MID に属する注文は「見つからない」として報告されます。
出金の 3 つの呼び出しはどのように組み合わせますか？
consult—currencyと、必要に応じてamountを送信します。手数料、受取予定額、 契約上の上限・下限、受取口座が返されるので、確定前に検証できます。create— 決定した金額と、お客様側で生成したwithdrawRequestIdを送信します。inquiry— ステータスが最終状態になるまでポーリングするか、notifyUrlへのコールバックを待ちます。
create は意図的に「完了した出金」ではありません。承認レコードと残高の引き落としは非同期で発生するため、成功した create は通常 IN_PROGRESS を返します — これは
「受理済み」として扱い、決して「支払済み」として扱わないでください。
consult は何を教えてくれますか？amount を省略した場合はどうなりますか？
amount を省略すると、consult は「今この瞬間に一度に出金できる最大額はいくらか」に答えます。すなわち
出金可能残高 — 精算アカウントの利用可能残高から、Reserve残高がマイナスの場合はその不足分を差し引いたもの — を、契約の最大額で上限として返します。
確定した
fxRate と actualReceiveAmount は、注文完了後に inquiry で表示されます。
create には何が必要で、冪等性はどのように動作しますか？
bankAccountId を省略すると、契約に紐づく唯一の口座が自動的に使用されます。契約に
複数の口座がある場合、省略するとパラメータエラーとなり、指定を求められます。accountNo
は同一通貨で複数の残高アカウントを持つ場合にのみ意味があります — これは別の Waffo エンティティと再契約した後に発生します。
withdrawRequestId は MID ごとにスコープされた冪等キーです。同じ amount と
currency で再送すると、元の注文の結果が返されます — 2 回目の出金は発生しません。異なる
amount または currency で再送すると、呼び出しは A0011 “Idempotent param mismatch error” で失敗します。したがって、
タイムアウト時は同一の本文で安全にリトライできます。本当に新しい出金には新しい ID が必要です。
ステータスはどのようにポーリングし、各ステータスは何を意味しますか？
inquiry には withdrawRequestId または withdrawOrderId のいずれか一方以上が必要です。どちらもない場合はパラメータエラーです。
両方送信した場合は withdrawOrderId が優先され、2 つが一致しない場合は誤った注文を返すのではなく、
呼び出しが失敗します。
Portal では同じ注文に対してより長く細かいステータス一覧が表示されます — 対応関係は
出金・一括 Payout FAQ にあります。成功時、
inquiry は
actualReceiveAmount、fxRate（同一通貨の場合は常に 1.00）、bankRefId、
withdrawCompleteTime を補完します。失敗時は failureCode と failureReason を含みます。
残高照会はどのアカウントを返しますか？
精算アカウントのみです — 精算通貨ごとに 1 行、契約エンティティごとにまとめられます。currency を渡すと絞り込めます。省略するとすべての通貨が返されます。精算待ち残高はここでは公開されません。
アカウント履歴照会はどこまで過去を遡れますか？各行には何が含まれますか？
このエンドポイントの時刻はすべて 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 などのコードで、大文字小文字を区別せずに照合するのが最善です — が含まれます。それぞれの意味は 残高・アカウント履歴 にあります。
どのエラーを明示的に処理すべきですか？
まだ解決しませんか？
withdrawRequestId または
withdrawOrderId と呼び出しのタイムスタンプを添えて、サポートにお問い合わせください。