コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン
概要
商品
Treasury

OutboundTransfer オブジェクトを使用して Treasury で送金

Treasury の金融口座から外部の口座に送金する方法をご紹介します。

OutboundTransfer オブジェクトは、金融口座からの送金を円滑にします。OutboundTransfer を使用して、ACH ネットワーク、または国内の電信送金を通じて、連結アカウントが所有する外部の銀行口座に資金を送金できます。

アウトバウンド送金は通常、電信送金または ACH のどちらを使用したかに応じて、同日から 2 営業日後に受け取り側の銀行に到着します。

注

Multi FA ベータ Multi FA ベータに登録している場合、OutboundTransfer を使用して、同じ連結アカウントに関連付けられている別の金融口座に stripe ネットワーク経由で資金を送金できます。資金は、宛先の金融口座に数分以内で入金されます。

詳細については、資金移動のタイムラインガイドをご覧ください。

OutboundTransfers は us_bank_account タイプの支払い方法に対応しています。または、ExternalAccount として、加盟店に属する既存の BankAccount を使用することもできます。

OutboundTransfer を作成する

POST /v1/treasury/outbound_transfers を使用し、関連付けられた ID の金融口座に対して OutboundTransfer を作成します。リクエストに使用可能なパラメーターのうち、4 つが必須です。

  • amount: セント単位での送金額。
  • currency: 3 文字の ISO 通貨コード。
  • financial_account: 資金を引き出す元となる金融口座 ID。
  • destination_payment_method: 送金先の PaymentMethod ID、または資金を受け取る BankAccount ID。
{
  // The source financial account to pull funds from.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to send. 10.00 USD in this case.
  "amount": 1000,
  "currency": "usd",
  // The destination PaymentMethod or BankAccount.
  "destination_payment_method": "{{PAYMENT_METHOD_ID}}"  | "{{BANK_ACCOUNT_ID}}",
  // Optionally, to explicitly specify a network, override the `network` value
  "destination_payment_method_options": {
    "us_bank_account": {
      "network": "ach" | "us_domestic_wire"
    }
  },
  // A description visible on the external bank statement.
  "statement_descriptor": "Bank xfer",
  // An optional internal description to identify this OutboundTransfer
  "description": "Transfer to my external account",
  // Stripe does not support updating originated transfers after creation.
  // You can only set metadata at creation.
  "metadata": nil | Hash,
}

以下のリクエストは、アカウントに関連付けされた PaymentMethod に、送金元が特定された金融口座となる OutboundTransfer を作成します。

Command Line
curl https://api.stripe.com/v1/treasury/outbound_transfers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}}
 \
  -d amount=1000 \
  -d currency=usd \
  -d destination_payment_method=
{{PAYMENT_METHOD_ID}}
 \
  -d statement_descriptor="Test xfer" \
  -d "destination_payment_method_options[us_bank_account][network]"=ach

成功すると、新しく作成された OutboundTransfer オブジェクトがレスポンスで返されます。

{
    "id": "{{OUTBOUND_TRANSFER_ID}}",
    "object": "outbound_transfer",
    "amount": 1000,
    "cancelable": true,
    "created": 1648479987,
    "currency": "usd",
    "description": null,
    "destination_payment_method": "{{PAYMENT_METHOD_ID}}",
    "destination_payment_method_details": {

同日の ACH

ベータ

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

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

同日の ACH を使用すると、カットオフ時間 までに OutboundTransfer コールが正常に完了した場合、同一営業日内に到着する売上を送信できます。 同日の ACH を使用するには、destination_payment_method_options.us_bank_account.network パラメーターを ach に設定し、destination_payment_method_options.us_bank_account.ach.submission パラメーターを same_day に設定します。

電信送金: 金融番号

一部の銀行では、ACH とは異なる別の電信送金の金融番号を使用することがあります。このため、支払い方法の金融番号が電信送金をサポートしていない場合、電信送金の作成時にエラーが発生することがあります。このエラーを受信した場合には、銀行の電信送金用の金融番号を指定して新しい支払い方法を追加する必要があります。

電信送金: 受取人の住所

電信送金には ACH メタデータのほかに、受取人名と請求先住所が必要です。住所は銀行の住所ではなく、電信送金を受け取るアカウント所有者の住所です。

支払い方法の billing_details.address を入力する際は、すべての住所フィールドに入力する必要があります。 billing_details.address に不完全なフィールドがある状態で電信送金しようとすると、エラーが発生します。

注

OutboundTransfer を使用して電信送金を行う際、住所フィールドに入力しない場合は、デフォルトで Stripe アカウント所有者を代表する法人に設定されます。

OutboundTransfer を取得する

GET /v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}} を使用して、関連付けられた ID の OutboundTransfer の詳細を取得します。

以下のリクエストは、関連付けられた ID の OutboundTransfer を取得し、Transaction の詳細を展開します。

Command Line
curl -G https://api.stripe.com/v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "expand[]"=transaction

成功すると、関連付けられた ID の OutboundTransfer オブジェクトがレスポンスで返されます。 レスポンスの一部のパラメーターには、expand[] パラメーターに値として追加した場合にのみ返される追加情報があります。次のレスポンス例で、拡張できるフィールドには、「Expandable」コメントが付いています。オブジェクトレスポンスの拡張の詳細については、レスポンスを拡張するをご覧ください。

{
  "id": "{{OUTBOUND_TRANSFER_ID}}",
  "object": "outbound_transfer",
  "livemode": Boolean,
  "created": Timestamp,
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  "destination_payment_method": "{{PAYMENT_METHOD_ID}}",
  "description": "Transfer to my external account",

OutboundTransfer をキャンセルする

POST /v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/cancel を使用し、関連付けられた ID の OutboundTransfer をキャンセルします。 OutboundTransfer オブジェクトには、送金をキャンセルできるかどうかを示すブール値を含む cancelable パラメーターが含まれます。OutboundTransfer がネットワークに送信されると、cancelable 値が false になり、このエンドポイントからの送金に対するエラーが受信されます。

Command Line
curl -X POST https://api.stripe.com/v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/cancel \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

成功すると、ステータスが canceled の OutboundTransfer オブジェクトがレスポンスで返されます。

{
    "id": "{{OUTBOUND_TRANSFER_ID}} ",
    "object": "outbound_transfer",
    "amount": 1000,
    "cancelable": false,
    "created": 1648487177,
    "currency": "usd",
    ...
    "status": "canceled",
    "status_transitions": {
        "canceled_at": 1648487198,
        "failed_at": null,
        "posted_at": null,
        "returned_at": null
    },
    "transaction": "{{TRANSACTION_ID}}"
}

OutboundTransfer をリストする

GET /v1/treasury/outbound_transfers を使用し、financial_account パラメーターの ID の金融口座から送信された OutboundTransfers をリストします。標準のリストパラメーターや status でリストをフィルタリングできます。

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

以下のリクエストは、特定された金融口座からの OutboundTransfers を取得します。含まれたパラメーターにより、レスポンスは、指定された ID の OutboundTransfer の後の最初の 3 件の送金に制限されます。

Command Line
curl -G https://api.stripe.com/v1/treasury/outbound_transfers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}}
 \
  -d limit=3 \
  -d starting_after={{OUTBOUND_TRANSFER_ID}}

成功すると、フィルター条件を満たす OutboundTransfer オブジェクト のリストがレスポンスで返されます。

OutboundTransfer の状態

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

ステータス説明状態の移行
processingOutboundTransfer の開始状態。資金は、保留中の取引に割り当てられます (ただし、引き続き現在の残高に含まれています)。cancelable パラメーターの値が true の間は 、ユーザーは OutboundTransfer をキャンセルできます。posted、canceled、failed
canceled (最終状態)ユーザーが、転記前に OutboundTransfer をキャンセルしました。Stripe は、保留中の取引を無効にし、資金をユーザーに返金します。該当なし
postedOutboundTransfer がネットワークに送信され、資金がアカウントから送金されました (取引が転記されました)。returned
returned (最終状態)OutboundTransfer は、送金先に正常に入金されませんでした (口座詳細に誤りがあった場合など)。Stripe は、returned_details[transaction] を指定して資金をユーザーに返金します。該当なし
failed (最終状態)OutboundTransfer がネットワークに送信されませんでした。Stripe は保留中の取引を無効にし、資金をユーザーに返金します。Stripe は、この状態を使用して内部エラーを通知する場合があります。該当なし

OutboundTransfer をテストする

テスト環境では、テスト環境用の支払い方法として destination_payment_method を指定できます。導入をテストする際は、テスト環境用の独自の PaymentMethods を作成することも、Stripe のテスト ID を使用することもできます。

タイプ結果支払い方法
us_bank_accountデフォルトは posted に移行します。pm_usBankAccount
us_bank_accountposted に移行し、元の expected_arrival_date に 1 日追加します。pm_usBankAccount_expectedArrivalDateUpdated
us_bank_accountprocessing のままになります。pm_usBankAccount_processing
us_bank_accountcanceled に移行します。pm_usBankAccount_canceledByUser
us_bank_accountfailed に移行します。pm_usBankAccount_internalFailure
us_bank_accountreturned_details.code="no_account" で returned に移行します。pm_usBankAccount_noAccount
us_bank_accountreturned_details.code="account_closed" で returned に移行します。pm_usBankAccount_accountClosed
us_bank_accountreturned_details.code="invalid_account_number" で returned に移行します。pm_usBankAccount_invalidAccountNumber

いずれの場合も、OutboundTransfer のレスポンスは processing の状態です。Stripe は、該当する状態の移行に対して Webhook をトリガーします。OutboundTransfer を作成後に取得すると、想定された状態が返されます。

OutboundTransfer のテスト用ヘルパーエンドポイント

Stripe は、さまざまな状態の OutboundTransfers をテストできるエンドポイントを提供しています。OutboundTransfer を作成した後、これらのエンドポイントを使用して、OutboundTransfer を posted、failed、canceled、または returned などの新しい状態に直接移行します。

  • テスト用の post エンドポイントを使用して、特定された OutboundTransfer を processing から posted に移行します。

    POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/post

  • テスト用の fail エンドポイントを使用して、特定された OutboundTransfer を processing から failed に移行します。

    POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/fail

  • テスト用の return エンドポイントを使用して、特定された OutboundTransfer を posted から returned に移行します。

    POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/return

これらのエンドポイントは、返品などのエラーシナリオをテストするために特に便利です。これらがなければ、外部でのアクションが必要になります。

return エンドポイントでは、オプションの returned_details.code パラメーターを本文に含め、返金理由を示します。この情報が提供されない場合、送金にはデフォルトの declined 返金コードが適用されます。

{
  "returned_details": {
    "code": "account_closed" |
          "account_frozen" |
          "bank_account_restricted" |
          "bank_ownership_changed" |
          "could_not_process" |
          "invalid_account_number" |
          "incorrect_account_holder_name" |
          "invalid_currency" |
          "no_account" |
          "declined"
  }
}

テスト用の update エンドポイント も用意されており、これを使用してテスト環境の Outbound Transfer における追跡の詳細情報の送信をシミュレーションできます。tracking_details フィールドは、テスト環境のオブジェクトに対してのみ設定できます。

いずれのケースでも、Stripe は、該当するそれぞれの状態の移行に対して Webhooks をトリガーします。移行後に OutboundTransfer を取得すると、想定される状態が返されます。

OutboundTransfer の Webhook

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

  • OutboundTransfer 作成時の treasury.outbound_transfer.created。
  • OutboundTransfer のステータスが変化した際の treasury.outbound_transfer.{{new_status}}。ステータス値のオプションには以下が含まれます。
    • treasury.outbound_transfer.posted
    • treasury.outbound_transfer.failed
    • treasury.outbound_transfer.returned
    • treasury.outbound_transfer.canceled
  • OutboundTransfer の expected_arrival_date が変化した際の treasury.outbound_transfer.expected_arrival_date_updated。
  • OutboundTransfer の追跡の詳細情報が更新された際の treasury.outbound_transfer.tracking_details_updated。
このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
Stripe の製品変更ログを確認してください。
ご不明な点がございましたら、お問い合わせください。
Powered by Markdoc
このページの内容
OutboundTransfer を作成する
同日の ACH
電信送金: 金融番号
電信送金: 受取人の住所
OutboundTransfer を取得する
OutboundTransfer をキャンセルする
OutboundTransfer をリストする
OutboundTransfer の状態
OutboundTransfer をテストする
OutboundTransfer のテスト用ヘルパーエンドポイント
OutboundTransfer の Webhook
使用製品
Treasury
Connect