コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要
事業で活用する
カード即時通貨換算
プラットフォームに組み込む
プラットフォーム向け金融口座

InboundTransfer オブジェクトを使用した資金移動

お持ちの他の口座から金融口座への送金方法をご紹介します。

インバウンド送金は、ACH ネットワークを使用して外部のアメリカの銀行口座から金融口座に資金を移動します。このような送金は、InboundTransfer オブジェクトで開始されます。

インバウンド送金は、即日 ACH 機能をご利用の場合を除き、完了までに 2 〜 4 営業日かかります。詳しくは、Money movement timelines ガイドをご覧ください。

メモ

インバウンド送金を使用して、金融口座所有者の銀行口座から資金を移動できます。インバウンド送金は、サードパーティーの外部口座から金融口座への資金移動に対応していません。サードパーティーの外部口座から金融口座への資金を受け付けるには、ACH デビットを使用して支払い残高に資金を追加し、その後金融口座に入金します。

InboundTransfer を作成する

POST /v1/treasury/inbound_transfers を使用して InboundTransfer オブジェクトを作成します。これは、お客様が保有する外部口座から自身の金融口座への引き出しベースの送金を表します。言い換えると、InboundTransfer を作成し、外部のアメリカの銀行口座から引き落としを行い、金融口座に資金を移動します。このリクエストには、以下のパラメーターを含める必要があります。

  • amount: 金融口座に送金されるセント単位での金額。
  • currency: 3 文字の ISO 通貨コード (サポートされている値は、現在 usd のみ)。
  • financial_account: 送金を受け取る金融口座の ID。
  • origin_payment_method: インバウンド送金の資金ソース。まず、インバウンドフロー用の口座付き支払い方法を設定し、SetupIntent を使用して銀行口座を検証する必要があります。または、検証済み ExternalAccount として設定済みの既存の BankAccount を使用することもできます。支払い方法を使用する場合も、銀行口座を使用する場合も、口座から資金を引き落とすには、口座所有者の許可 が必要です。

以下の JSON は、リクエストの本文に含めることができるデータを示します。 

{
  // The source PaymentMethod or BankAccount. Funds are pulled from this account.
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}" | "{{BANK_ACCOUNT_ID}}",
  // The destination FinancialAccount. Funds arrive in this account.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to debit. 10.00 USD in this case.
  "amount": 1000,
  "currency": "usd",
  // An optional, internal description for the InboundTransfer.
  "description": "Funds for vendor payment payment_234281",
  // An optional descriptor for the InboundTransfer to send
  // to the network with the debit request. Max 10 characters
  "statement_descriptor": "payment_1",
  // Stripe doesn't support updating InboundTransfers after creation.
  // You can only set metadata at creation time.
  "metadata": null | {{Hash}}
}

以下のリクエストは、アカウントに関連付けられた支払い方法を使用して 200 USD を指定された ID の金融口座に送金します。Stripe-Account ヘッダー値は、金融アカウントと支払い方法の両方を所有する Stripe アカウントを識別します。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/treasury/inbound_transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d origin_payment_method=
"{{PAYMENT_METHOD_ID}}"
 \
  -d financial_account=
"{{FINANCIAL_ACCOUNT_ID}}"
 \
  -d amount=20000 \
  -d currency=usd \
  -d description="Funds for repair" \
  -d statement_descriptor="Invoice 12"

成功すると、レスポンスで InboundTransfer オブジェクトが提供されます。このオブジェクトには、hosted_regulatory_receipt_url が含まれ、お客様のプラットフォームのアカウント所有者が取引詳細にアクセスできるようにします。

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Funds for repair",
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{IBT_URL}}",
    "linked_flows": null,
    "livemode": false,
    "metadata": {},
    "origin_payment_method": "{{PAYMENT_METHOD_ID}}",
    ...
    "statement_descriptor": "Invoice 12",
    "status": "processing",
    ...
}

警告

まれに、 Stripeがさまざまなリスク要因により InboundTransfer リクエストをキャンセルすることがあります。これらのシナリオでは、 API リクエストがレスポンスコード 402 でエラーになります。エラーメッセージには、エラーにつながったリスク要因の詳細が表示されています。

同日の ACH

プライベートプレビュー

同日の ACH は現在、制限付きのプレビュー版として提供されているため、Stripe の審査と承認が必要です。アクセスをリクエストするには、treasury-support@stripe.comにメールを送信してください。

アクセスできない場合、同日の ACH の機能またはパラメーターを含む API コールがエラーを返します。

同日 ACH を使用すると、InboundTransfer の呼び出しが 締切時間 より前に正常に完了した場合、同じ営業日内に資金が送金元の金融口座に到着します。同日 ACH を使用するには、origin_payment_method_options.us_bank_account.ach.submissionパラメーターを same_day に設定します。

当日 ACH の提供による不正利用リスク

即日 ACH インバウンド送金の迅速な決済により、プラットフォームは通常の ACH インバウンド送金よりも大きな財務リスクにさらされる可能性があります。例えば、連結アカウントがインバウンド送金を開始し、送金元口座の資金不足により返送されることがあります。当日中に決済を行うと、資金が返却される前に金融口座から資金を引き落とす可能性があります。連結アカウントが資金を引き落とし、その返戻によって金融口座の残高がマイナスになった場合、プラットフォームが責任を負います。

Stripe の不正利用防止システムがインバウンド送金を高リスクのアクティビティと見なした場合、作成リクエストはエラーで失敗します。

{
  "error": {
    "type": "invalid_request_error",
    "message_code": "inbound_transfer_not_same_day_eligible",
    "message": "This transaction is not eligible for same-day availability at this time. Please try again with `standard` ACH submission."
  }
}

inbound_transfer_not_same_day_eligible メッセージコードのエラーが発生した場合は、origin_payment_method_options.us_bank_account.ach.submission パラメーターを standard に設定してリクエストを再試行します。

InboundTransfer を取得する

GET /v1/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}} を使用し、関連付けられた ID の InboundTransfer オブジェクトを取得します。

以下の JSON は、リクエストの本文に含めることができるデータを示します。 レスポンスの一部のパラメーターには、expand[] パラメーターに値として追加した場合にのみ返される追加情報があります。次のレスポンス例で、拡張できるフィールドには、「Expandable」コメントが付いています。オブジェクトレスポンスの拡張の詳細については、レスポンスを拡張するをご覧ください。

{
  "id": "{{INBOUND_TRANSFER_ID}}",
  "object": "inbound_transfer",
  "livemode": false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  // The only current valid PaymentMethod type for InboundTransfers is us_bank_account
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}",

次のリクエストは、id 値が {{INBOUND_TRANSFER_ID}} の InboundTransfer を取得します。本文の expand[] 配列に transaction を含めると、該当する情報が展開されて返されます。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -G https://api.stripe.com/v1/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "expand[]"=financial_account

成功すると、拡張された情報を持つ InboundTransfer オブジェクトがレスポンスで返されます。

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Inbound transfer",
    "failure_details": null,
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{INBOUND_TRANSFER_ID}}",

InboundTransfer を一覧表示する

GET /v1/treasury/inbound_transfers を使用し、関連付けられた ID の金融口座のすべての InboundTransfers を取得します。標準のリストパラメーターまたは status でリストをフィルタリングできます。

{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by status
  "status": "processing" | "succeeded" | "failed",
  // Filter by FinancialAccount (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Required
}

以下のリクエストは、ID {{CONNECTED_ACCOUNT_ID}} の連結アカウントに関連付けらた、ID {{FINANCIAL_ACCOUNT_ID}} の金融口座について、ステータスが succeeded のインバウンド送金をすべて取得します。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -G https://api.stripe.com/v1/treasury/inbound_transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
"{{FINANCIAL_ACCOUNT_ID}}"
 \
  -d status=succeeded

InboundTransfers を手動で確認する

銀行パートナーへの送金を遅らせるか、売上を長期間保留することで、送金のリスクを軽減できます。この保留により、不審なアクティビティを確認するための時間が増える可能性があります。inbound_transfers.ach.platform_review の機能へのアクセスをリクエストすると、ステータスが requires_confirmation のインバウンド送金を、この機能が有効になっている金融口座ですべて受け取れるようになります。

以下は、新しい金融口座でこの機能を設定する例です。他の機能を追加することもできます。

Command Line
cURL
No results
curl https://api.stripe.com/v1/treasury/financial_accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "supported_currencies[]"=usd \
  -d "inbound_transfers[ach][requested]"=true \
  -d "inbound_transfers[ach][platform_review][requested]"=true

以下は、既存の金融口座でこの機能を設定する例です。

Command Line
cURL
No results
curl https://api.stripe.com/v1/treasury/financial_accounts/fa_xxx/features \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "supported_currencies[]"=usd \
  -d "inbound_transfers[ach][requested]"=true \
  -d "inbound_transfers[ach][platform_review][requested]"=true

通常、インバウンド送金は作成時に自動的に銀行に送金されます。ただし、ステータスが requires_confirmation のインバウンド送金では、銀行パートナーに送金を送信する前に /v1/treasury/inbound_transfers/{id}/confirm エンドポイントでユーザーの明示的な確認を取る必要があります。送金を確定またはキャンセルする前に、インバウンド送金の詳細とリスクシグナルを確認できます。ステータスが requires_confirmation のインバウンド送金は、5 営業日以内に確定またはキャンセルしてください。5 営業日を過ぎると、送金は自動的にキャンセルされます。たとえば、金曜日に作成された requires_confirmation のインバウンド送金は、翌週の金曜日までに確定させる必要があります (アメリカで祝日がない場合)。

confirm エンドポイントで funds_availability_delay パラメーターを使用して、目的の金融口座に資金をリリースするまでの遅延時間 (秒単位) を指定します。これにより、追加の遅延を利用して、送金を手動で確認できます。また、このフィールドを使用して、ACH の差戻し期間を過ぎても資金を保持し、元の銀行が遅延後に資金を取り消すことができないようにすることもできます。funds_availability_delay を 432,000 に設定して、差戻し期間後に資金がリリースされるようにすると、さらにセキュリティが高まります。

以下は、可用性の遅延なしで confirm エンドポイントを呼び出す例です。

Command Line
cURL
No results
curl -X POST https://api.stripe.com/v1/treasury/inbound_transfers/ibt_xxx/confirm \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

以下は、可用性の遅延を指定して confirm エンドポイントを呼び出す例です。

Command Line
cURL
No results
curl https://api.stripe.com/v1/treasury/inbound_transfers/ibt_xxx/confirm \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d funds_availability_delay=432000

InboundTransfer の状態

以下の表は、各ステータスと可能な移行状態について説明したものです。

ステータス説明状態の移行
processingInboundTransfer の作成に成功しました。Stripe はネットワークでの売上の送金を指示します。failed、canceled、succeeded、requires_confirmation
requires_confirmationInboundTransfer は保留状態で作成されます。Stripe がネットワーク上で資金の移動を開始していないときは、ユーザーは /v1/treasury/inbound_transfers/:ID/confirm エンドポイントを使用してこのインバウンド送金をトリガーする意図を明示する必要があります。processing、canceled
failed (最終状態)InboundTransfer の確定に失敗しました。取引は作成されず、payment_method は引き落としされていません。該当なし
canceled (最終状態)InboundTransfer はネットワークへの送信前にキャンセルされました。Stripe は取引を無効化し、売上を外部の銀行口座から移動しません。該当なし
succeeded (最終状態)InboundTransfer が成功し、資金がアカウントに入金されました。取引が作成されました。外部の口座が資金を引き出した場合、InboundTransfer は成功した後で返金されることがあります。これは、関連付けられた ReceivedDebit によって表されます。該当なし

InboundTransfer をテストする

実装をエンドツーエンドでテストするには、test SetupIntents requests を使用して PaymentMethod を作成し、その PaymentMethod を InboundTransfer 作成リクエストに渡します。PaymentMethods が有効であれば InboundTransfers は成功し、無効な PaymentMethods が無効であれば (サポートされていないタイプ、未確認の銀行口座を含む、インバウンドフロー用に設定されていない、など) 本番環境と同じエラーをスローします。

InboundTransfer の状態をテストする

Stripe では、テスト用の PaymentMethod トークンのセットも用意しています。これを使用すると、次のような特定の状態の移行をトリガーできます。

PAYMENT_METHOD の値結果
pm_usBankAccountprocessing から succeeded に移行する InboundTransfer。
pm_usBankAccount_processingprocessing 状態のままの InboundTransfer。
pm_usBankAccount_internalFailureprocessing から failed に移行する InboundTransfer。

さまざまなエッジケースをより迅速にテストするために、PaymentMethod のトークンは以下の特定の失敗タイプをシミュレーションします。

PAYMENT_METHOD の値結果
pm_usBankAccount_noAccountfailure_details.code= "no_account" で失敗に移行する InboundTransfer。
pm_usBankAccount_accountClosedfailure_details.code= "account_closed" で failed に移行する InboundTransfer。
pm_usBankAccount_invalidAccountNumberfailure_details.code= "invalid_account_number" で失敗に移行する InboundTransfer。
pm_usBankAccount_insufficientFundsfailure_details.code= "insufficient_funds" で失敗に移行する InboundTransfer。
pm_usBankAccount_debitNotAuthorizedfailure_details.code= "debit_not_authorized" で失敗に移行する InboundTransfer。
pm_usBankAccount_disputeprocessing から succeeded に移行し、後で不審請求の申請が行われる InboundTransfer。inbound_transfer.returned が true になり、関連付けられた ReceivedDebit が作成されます

上記のすべてのケースで、InboundTransfer のレスポンスは processing 状態で始まります。関連する状態へと移行するたびに Webhook イベントが受信され、作成後に InboundTransfer を取得すると、想定された状態が返されます。

PaymentMethod として pm_usBankAccount_sameDayACHIneligible トークンを渡すことでも、エラー状態をテストすることができます。これにより、InboundTransfer (同日の ACH 送信を伴う) の作成がトリガーされ、エラーが返されます。

InboundTransfer テストヘルパーエンドポイント

Stripe では、さまざまな状態の InboundTransfers をテストできるエンドポイントも提供しています。InboundTransfer を作成し、以下の手順に従います。

  • テスト用の succeed エンドポイント を使用し、関連付けられた ID の送金を直接 succeeded 状態に移行します。

    POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/succeed

  • テスト用の fail エンドポイント を使用し、関連付けられた ID の送金を直接 failed の状態に移行します。

    POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/fail

これらのエンドポイントは、返品などのエラーシナリオをテストするために特に便利です。こういったエンドポイントがなければ、InboundTransfer が資金を引き出していた外部の口座からのアクションが必要になります。

本文にオプションの failure_details.code パラメーターを含め、送金が失敗した理由を示します。この情報が提供されない場合には、送金はデフォルトの could_not_process 失敗コードで失敗します。

{
  "failure_details": {
    "code": "account_closed" |
          "account_frozen" |
          "bank_account_restricted" |
          "bank_ownership_changed" |
          "could_not_process" | // Generic fallback code
          "invalid_account_number" |
          "incorrect_account_holder_name" |
          "invalid_currency" |
          "no_account"
  }
}

プラットフォーム向け金融口座は、成功したが後で返された InboundTransfer をシミュレートする return エンドポイントも提供します。

テスト用の return エンドポイント を使用し、関連付けられた ID の InboundTransfer で返金のシミュレーションを開始します。

POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/return

すべてのテスト用エンドポイントは、該当するそれぞれの状態の移行に対して Webhooks をトリガーします。移行後に InboundTransfer を取得すると、想定される状態が返されます。

InboundTransfer Webhook

Stripe は、Webhook エンドポイントに以下の InboundTransfer イベントを送信します。

  • InboundTransfer 作成時の treasury.inbound_transfer.created。
  • InboundTransfer のステータスが変化した際の treasury.inbound_transfer.{{new_status}}。ステータス値のオプションには以下が含まれます。
    • treasury.inbound_transfer.succeeded
    • treasury.inbound_transfer.failed