alpaca-broker-funding-transfers

Alpaca Broker API — 入出金と振替

エンドユーザーの口座への入金と口座からの出金です。3 種類の外部決済経路に加えて Instant Funding があり、外部決済経路ではモデルが銀行口座リンク（永続的なもの）と振替（実際の資金移動）に明確に分かれています。

ベース URL と認証（クライアント認証情報による Bearer トークン。従来の Basic も引き続き使用できます）については、まず alpaca-broker-integration をお読みください。オムニバス口座内での口座間の資金移動（外部との入出金ではなく）については、alpaca-broker-journals をご覧ください。これは別の仕組みです。

参考資料

• ガイド：https://docs.alpaca.markets/docs/funding-accounts
• API リファレンス：https://docs.alpaca.markets/reference/createtransferforaccount
• ライブスキーマ：alpaca-docs MCP → get-endpoint タイトル "Broker API" パス /v1/accounts/{account_id}/transfers

1. 入出金モデル

External bank ──(relationship: a persistent link)──┐
                                                    ├──> Transfer (the money movement) ──> Account cash
ACH relationship  (rail A: ACH, US domestic)        │
Bank relationship (rail B: wire, domestic + intl)   │
Funding wallet    (rail C: v1beta, multi-currency)  ┘

• リレーションシップは外部銀行口座を関連付けます。資金移動は行わず、独自のステータスを持ちます。電信送金の場合、振替を進めるにはステータスが APPROVED である必要があります。
• 振替は ID でリレーションシップを参照し、資金を移動します。1 つのリレーションシップを複数の振替で使用できます。

決済経路	transfer_type	方向	リレーションシップ	備考
ACH	ach	INCOMING + OUTGOING	ACH リレーションシップ（relationship_id）	米国内のみ。Plaid の processor_token で設定（推奨）
電信送金	wire	OUTGOING のみ	銀行リレーションシップ（bank_id）	国内および国際（SWIFT）。入金電信送金は送金元銀行から送信され、自動的に計上されます
入出金ウォレット	（別の /v1beta API）	incoming / outgoing（小文字）	入出金ウォレットの受取銀行口座	複数通貨に対応し、swift_wire / local_rails を使用
Instant Funding	（別の /v1/instant_funding API）	入金のみ	なし — お客様自身で支払いを回収します	購買余力が即時に増加し、T+1 に電信送金で一括決済されます。§8 を参照

2. エンドポイント

メソッド	パス	用途
POST/GET/DELETE	/v1/accounts/{id}/ach_relationships[/{rel_id}]	ACH 銀行口座リンクの管理
POST/GET/DELETE	/v1/accounts/{id}/recipient_banks[/{bank_id}]	電信送金の受取銀行口座の管理
POST	/v1/accounts/{id}/transfers	振替の作成（ACH 入金／出金、または電信送金による出金）
GET	/v1/accounts/{id}/transfers	振替の一覧取得
DELETE	/v1/accounts/{id}/transfers/{transfer_id}	キャンセルのリクエスト
POST/GET	/v1beta/accounts/{id}/funding_wallet	入出金ウォレットの作成／取得
GET	/v1beta/accounts/{id}/funding_wallet/funding_details	ウォレットへの入金手順
POST/GET/DELETE	/v1beta/accounts/{id}/funding_wallet/recipient_bank	入出金ウォレットの受取銀行口座
POST	/v1beta/accounts/{id}/funding_wallet/withdrawal	入出金ウォレットからの出金
GET	/v1beta/accounts/{id}/funding_wallet/transfers[/{transfer_id}]	ウォレット振替の一覧取得／取得
POST/GET/DELETE	/v1/instant_funding[/{instant_funding_id}]	Instant Funding 振替の作成／取得／取り消し
GET	/v1/instant_funding/limits	コルレス先レベルの上限（口座ごとの上限は /limits/accounts）
POST	/v1/instant_funding/settlements	作成済みの振替の決済を開始
GET	/v2/events/funding/status	SSE — 統合入出金ステータスストリーム（§6 を参照）

現在の電信送金用銀行口座エンドポイントは /recipient_banks です（スキーマは Bank / CreateBankRequest）。以前の /banks という名前はレガシーエイリアスです。

ウォレットへの入金フロー： ウォレットを作成 → GET .../funding_wallet/funding_details で顧客に案内する手順を取得 → 顧客が資金を送金（サンドボックスでは POST /v1beta/demo/banking/funding）→ GET .../funding_wallet/transfers をポーリングします。

3. 送金リクエストの作成（POST /v1/accounts/{id}/transfers）

すべてのリクエストで必須：transfer_type、amount（10 進数の文字列、0 より大きい値）、direction。

// ACH deposit
{ "transfer_type": "ach", "relationship_id": "<uuid>", "amount": "100.00", "direction": "INCOMING" }

// Wire withdrawal
{ "transfer_type": "wire", "bank_id": "<uuid>", "amount": "500.00", "direction": "OUTGOING",
  "fee_payment_method": "user", "additional_information": "..." }

• relationship_id は ach の場合に必須です。bank_id は wire の場合に必須で、もう一方は空でなければなりません。
• fee_payment_method（wire）：user（手数料を amount から差し引くため、UI でユーザーに警告します）または invoice（企業に月次で請求します）。自動処理される wire 手数料は送金側のものに限られます。
• additional_information は wire のみで使用できます。wire 以外のリクエストで送信すると 422 が返されます。
• Transfer レスポンスには、id、status、fee、requested_amount（元の要求額）、reason、タイムスタンプが追加されます。

4. wire 受取人の銀行口座（POST /v1/accounts/{id}/recipient_banks）

必須：name、bank_code、bank_code_type、account_number。

• bank_code_type：ABA（国内送金用の 9 桁のルーティング番号）または BIC（国際送金用の SWIFT）。
• BIC の場合、country、city、state_province、postal_code、street_address が必須になります。
• 仲介銀行／コルレス銀行の BIC は extra_fields（intermediary_bank1_bic など）に指定します。国際 wire でこれらを省略すると、自動選択、遅延、追加手数料が発生する可能性があります。国境を越える送金では、あらかじめ情報を収集してください。
• 新しい銀行口座は QUEUED で開始します。その口座への wire 送金が進行する前に、ステータスが APPROVED になる必要があります。

5. 送金ステータスの状態遷移

従来型の送金（TransferStatus）： QUEUED → APPROVAL_PENDING → PENDING → SENT_TO_CLEARING → (APPROVED) → COMPLETE。失敗時は REJECTED／CANCELED／RETURNED に遷移します。

終端ステータス	意味
COMPLETE	決済済み
REJECTED	拒否
CANCELED	クライアントによるキャンセル
RETURNED	銀行が ACH リターンを発行

（SSE の Transfer エンティティは、実質的に終端ステータスである EXPIRED も報告します。）

ファンディングウォレットの送金： PENDING → EXECUTED → COMPLETE。それ以外の終了状態として、REJECTED（銀行による拒否。通常は入力不備）と FAILED（銀行エラー）があります。ウォレットの送金はキャンセルできません。終端ステータスは COMPLETE／REJECTED／FAILED です。OpenAPI の FundingWalletTransferStatus enum には依然として CANCELED が記載されている一方、REJECTED は含まれていません。ガイドに従い、これらのステータスの組み合わせを終端として扱ってください。ここでの方向は小文字の incoming／outgoing で、従来型の送金とは大文字・小文字の使い方が異なる点に注意してください。

6. イベントとポーリング — 信頼性に関する重要な教訓

従来型の送金には SSE ストリームがあります： GET /v2/events/funding/status。4 つの entity_type 値（Transfer、BankRelationship、WireBank、FundingWallet）を統合しており、since／until（タイムスタンプ）または since_id／until_id（ULID）を使って再生できます。従来型の ACH／wire のステータス確認には、ポーリングではなくこちらを使用してください。

ファンディングウォレットの個々の送金ステータスは、プッシュ通知されないようです。ストリームに含まれるのはウォレットレベルのステータス（active／pending）のみです。ウォレットの個々の送金ステータス（PENDING→EXECUTED→COMPLETE）は、GET /v1beta/.../funding_wallet/transfers/{id} を使ってポーリングする必要があります。

教訓（苦労して得たもの）： イベントの対象範囲は送金レールによって異なります。送金レールごとに SSE を利用するかポーリングするかを決め、イベントでカバーされない項目（および SSE が途切れる可能性があるため、カバーされている項目についても安全策として）のためにステータス照合用ポーラーを構築してください。各 Alpaca ステータスを明示的な対応表で独自の内部ステータスにマッピングし、非終端状態の送金のみをポーリングしてください。alpaca-broker-reconciliation-idempotency を参照してください。

従来の方式に関する注意：旧 us/sse-events の「Transfer Events」ペイロードでは event_id に整数を使用し、ステータスは小文字です。新しい /v2/events/funding/status では ULID を使用します。v2 に移行してください。

7. ドキュメントに記載されている注意点

• 送金手数料（2022-06-01以降）： 国内および国際送金の出金には手数料がかかります。UI では requested_amount と amount＋fee の違いを反映してください。
• 入金送金を自動処理するには、FFC（For Further Credit）指示が必要です。 ない場合は手動で処理されます。
• トラベルルール： Alpaca は、通常の FinCEN の 3,000 ドル基準額を下回る場合でも、すべての入金について送信者／送金依頼人の情報を要求します。 決済の作成時に渡してください。5 年以上保持されます。
• ACH は Plaid を使用します： 銀行口座は processor_token で渡してください。リレーションシップには instant フラグがあります。口座種別は CHECKING／SAVINGS に限られます。
• 権限エラー： 口座に入金または出金の権限がない場合は 403 が返されます。エラーメッセージには失敗した権限（depositable_status／withdrawable_status）が示されます。これらは口座オブジェクトのフィールドではないため、事前に確認する方法はありません。403 を処理し、メッセージを表示してください。入金送金の試行、リレーションシップと銀行 ID の欠落または不一致、（文書化されていない）最低金額未満の場合は 422 が返されます。
• サンドボックスでの送金動作： エンドツーエンドでシミュレートされますが、非同期で、平日のみ自動完了します。週末に送信した場合、月曜日まで処理は進みません。（サンドボックスの ACH は即時に決済されます。）

8. 即時利用：対応している 2 つのモデル

Alpaca では、現金が着金する前にユーザーが取引できるようにする方法を 2 つ説明しています。それぞれ決済に関する義務が異なります。

現金プーリング（オムニバス＋ジャーナル） — ドキュメントでは、これが最も一般的なユースケースとされています。事前に資金を入れた自社口座へ一括送金し、ユーザーからの入金を受け取った時点で JNLC によりユーザー口座へ振り替えます。出金時は逆の処理を行います。事前に資金を用意するため、振替ごとに Alpaca へ支払う必要はありません。Alpaca の審査が必要で、地域によっては送金業者のライセンスが必要となる場合があります。alpaca-broker-journals を参照してください。

即時入金 — POST /v1/instant_funding は事前に資金を用意せずにユーザー口座の購買力を拡大するため、Alpaca が貴社に信用を供与し、後から決済する仕組みです。口座ごとの上限はデフォルトで 1,000 米ドル（申請により引き上げ可能）です。コルレス口座の利用可能枠は GET /v1/instant_funding/limits、口座ごとの利用可能枠は GET /v1/instant_funding/limits/accounts?account_numbers=… で確認できます。

決済は貴社の義務であり、期限が厳格です。振替は 24 時間単位の期間（米国東部時間午後 8 時終了）でバッチ処理されます。SI の自社口座へ一括送金した後、T+1 の米国東部時間午後 1 時までにトラベルルールの originator_* フィールドを含めて POST /v1/instant_funding/settlements を呼び出してください。決済が遅れると、FED UB＋8％の遅延利息が発生し、月次で請求されます。照合されていない振替は T+1 の米国東部時間午後 8 時に自動キャンセルされます。顧客がすでに信用分を使用していた場合、口座は借方残高になります。全体の手順については、https://docs.alpaca.markets/us/docs/instant-funding を参照してください。

関連スキル： 内部の現金移動 → alpaca-broker-journals；ステータスの未反映からの復旧 → alpaca-broker-reconciliation-idempotency；金額の書式設定 → alpaca-broker-money-precision；リアルタイムのステータス → alpaca-broker-sse-events。