OutboundTransfer オブジェクトを使用して 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
を作成します。
注
同日の ACH ベータ オプションの destination_payment_method_options[us_bank_account][ach][submission]=same_day
パラメーターを指定すれば、カットオフ時間前に OutboundTransfer
コールが正常に完了した場合、同一営業日に到着する ACH ネットワークを介して送金できます。OutboundPayment
の作成時にこのパラメーターが含まれていない場合、取引ではデフォルトの資金移動タイムラインが使用されます。この機能を使用するときは、destination_payment_method_options[us_bank_account][network]=ach
を含めてください、同日の ACH ベータの待機リストへの登録については、treasury-support@stripe.com までお問い合わせください。
成功すると、新しく作成された 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 のほかに、受取人名と請求先住所などの追加メタデータが必要です。指定する住所は、銀行の住所ではなく、電信送金を受け取る口座保有者の住所である必要があります。
決済手段の 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」コメントが付いています。オブジェクトレスポンスの拡張の詳細については、レスポンスを拡張するをご覧ください。
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 | OutboundTransfer がネットワークに送信され、資金がアカウントから送金されました (取引が転記されました)。 | 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_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" } }
テスト用の 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
。