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。
destination_payment_method_data: 資金を受け取る金融口座。

{
  // 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.
  // This should be nil if destination_payment_method is set.
  destination_payment_method_data: {
  type: "financial_account", // us_bank_account is not supported
  financial_account: "{{FINANCIAL_ACCOUNT_ID}}",
  },

  // This should be nil if destination_payment_method_data is set.
  "destination_payment_method": "{{PAYMENT_METHOD_ID}}"  | "{{BANK_ACCOUNT_ID}}",
  // Optionally, to explicitly specify a network, override the `network` value
  // This should be nil if destination_payment_method_data is set.
  "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 を作成します。

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

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

同日の ACH

プライベートプレビュー

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

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

Using same-day ACH enables sending funds that arrive the same business day if the OutboundTransfer call successfully completes before the cutoff time. To use same-day ACH, set the destination_payment_method_options.us_bank_account.network parameter to ach and the destination_payment_method_options.us_bank_account.ach.submission parameter to 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 の詳細を展開します。

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

JSON (コメント付き)
{
  "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 になり、このエンドポイントからの送金に対するエラーが受信されます。

成功すると、ステータスが 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 件の送金に制限されます。

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

OutboundTransfer の状態

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

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

OutboundTransfer をテストする

テスト環境では、テスト用決済手段として destination_payment_method を指定できます。独自のテスト用の PaymentMethods を作成するか、実装のテスト時にテスト用 ID を使用できます。

タイプ	結果	決済手段
`us_bank_account`	デフォルトは `posted` に移行します。	`pm_usBankAccount`
`us_bank_account`	`posted` に移行し、元の `expected_arrival_date` に 1 日追加します。	`pm_usBankAccount_expectedArrivalDateUpdated`
`us_bank_account`	`processing` のままになります。	`pm_usBankAccount_processing`
`us_bank_account`	`canceled` に移行します。	`pm_usBankAccount_canceledByUser`
`us_bank_account`	`failed` に移行します。	`pm_usBankAccount_internalFailure`
`us_bank_account`	`returned_details.code="no_account"` で `returned` に移行します。	`pm_usBankAccount_noAccount`
`us_bank_account`	`returned_details.code="account_closed"` で `returned` に移行します。	`pm_usBankAccount_accountClosed`
`us_bank_account`	`returned_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"
  }
}

また、テスト用の 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。