OutboundPayment オブジェクトを使用して Treasury で送金
OutboundPayment
オブジェクトは、Treasury 金融アカウントからの追加ベースの送金を表します。これには、ACH または電信送金経由でサードパーティーの外部口座に送金するものや、stripe
ネットワークを使用して同じプラットフォームに関連付けられている別の金融口座に即時送金するものがあります。たとえば、金融口座から、ベンダーの外部のアメリカの銀行口座に送金するには、OutboundPayment
を作成して資金を移動します。OutboundPayment
の受け取り側の口座は、外部銀行口座または別の金融口座です。
一般的なアウトバウンド支払いにかかる時間は、数分 (Stripe ネットワークを使用する場合)、同日中、1 ~ 2 営業日 (ACH ネットワークを使用する場合) といったようにさまざまです。詳細については、資金移動のタイムラインのガイドをご覧ください。
OutboundPayment を作成する
POST /v1/treasury/outbound_payments
を使用して OutboundPayment
を作成します。リクエストに使用可能なパラメーターのうち、以下は必須です。
amount
: セント単位での支払い金額。currency
: 3 文字の ISO 通貨コード (サポートされるのはusd
のみ)。financial_account
: 資金が送金される支払い元の金融口座。destination_payment_method
またはdestination_payment_method_data
: 支払いの送金先に関する情報。destination_payment_method
では、まず SetupIntent (支払いインテント) を使用して、アウトバウンドフローのPaymentMethod
を設定する必要があります。また、PaymentMethod
が関連付けられるCustomer
オブジェクトと一致する顧客 ID を指定する必要もあります。別の方法として、Customer
に関連付けられた既存のレガシーの BankAccount をPaymentMethod
の代わりに使用することもできます。destination_payment_method_data
を使用すると、インラインで決済手段の詳細を指定できます。これは、銀行口座の詳細の指定や、Stripe ネットワーク経由の別の金融口座への送金に使用できます。
外部の銀行口座に対する OutboundPayment を作成する
POST /v1/treasury/outbound_payments
を使用して、本文の financial_account
パラメーター値の ID で特定された金融口座から OutboundPayment
を作成します。以下のリクエストは、statement_descriptor
と destination_payment_method_data
の情報を追加します。
注
destination_payment_method_options[us_bank_account][ach][submission]=same_day
パラメーターを指定すれば、カットオフ時間前に OutboundPayment
コールが正常に完了した場合、同一営業日に到着する ACH ネットワークを介して送金できます。OutboundPayment
の作成時にこのパラメーターが含まれていない場合、取引ではデフォルトの資金移動タイムラインが使用されます。この機能を使用するときは、destination_payment_method_options[us_bank_account][network]=ach
を含めてください、同日の ACH ベータの待機リストへの登録については、treasury-support@stripe.com までお問い合わせください。成功すると、新しく作成された OutboundPayment
がレスポンスで返されます。
電信送金: 金融番号
一部の銀行では、ACH とは異なる別の電信送金の金融番号を使用することがあります。このため、決済手段の金融番号が電信送金をサポートしていない場合、電信送金の作成時にエラーが発生することがあります。このエラーを受信した場合には、銀行の電信送金用の金融番号を指定して新しい決済手段を追加する必要があります。
電信送金: 受取人の住所
電信送金には、ACH のほかに、受取人名と請求先住所などの追加メタデータが必要です。指定する住所は、銀行の住所ではなく、電信送金を受け取る口座保有者の住所である必要があります。
決済手段の billing_details.address
を入力する際は、すべての住所フィールドに入力する必要があります。 billing_details.address
に不完全なフィールドがある状態で電信送金しようとすると、エラーが発生します。
注
OutboundTransfer
を使用して電信送金を行う際、住所フィールドに入力しない場合は、デフォルトで Stripe アカウント所有者を代表する法人に設定されます。
金融アカウントに対する OutboundPayment を作成する
POST /v1/treasury/outbound_payments
を destination_payment_method_data
属性で定義した別の金融口座と組み合わせて使用し、金融口座間で資金を移動します。どちらの金融口座も、同一のプラットフォームに関連付けられている必要がありますが、連結アカウントに関連付けられた金融口座でも、プラットフォームの金融口座でも構いません。
リクエストの本文は、x-www-form-urlencoded
でなければなりませんが、以下の JSON は、送信できるデータを定義します。
OutboundPayment を取得する
GET /v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}
を使用し、関連付けられた ID の OutboundPayment
の詳細を取得します。
成功すると、関連付けられた ID の OutboundPayment
オブジェクトがレスポンスで返されます。 レスポンスの一部のパラメーターには、expand[]
パラメーターに値として追加した場合にのみ返される追加情報があります。次のレスポンス例で、拡張できるフィールドには、「Expandable」コメントが付いています。オブジェクトレスポンスの拡張の詳細については、レスポンスを拡張するをご覧ください。
OutboundPayment をキャンセルする
POST /v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/cancel
を使用し、関連付けられた ID の OutboundPayment
をキャンセルします。OutboundPayment
オブジェクトには、送金をキャンセルできるかどうかを示すブール値を含む cancelable
パラメーターが含まれます。OutboundPayment
がネットワークに送信されると、cancelable
値が false
になり、このエンドポイントからの送金に対するエラーが受信されます。
成功すると、レスポンスで、status
値が canceled
に設定された OutboundPayment
オブジェクトが返されます。
{ "id": "{{OUTBOUND_PAYMENT_ID}}", "object": "outbound_payment", "livemode": false, "created": 123456, "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", "amount": 1000, "currency": "usd", ... "status": "canceled",
OutboundPayment をリストする
GET /v1/treasury/outbound_payments
を使用し、関連付けられた ID の金融口座からの OutboundPayments
をリストします。標準のリストパラメーターや、status
または customer
でリストをフィルタリングできます。
{ // Standard list parameters "limit", "starting_after", "ending_before", // Filter by status "status": "processing" | "canceled" | "failed" | "posted" | "returned", // Filter by FinancialAccount (Required) "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Filter by Customer "customer": "{{CUSTOMER_ID}}", }
以下のリクエストは、プラットフォームに関連付けられた金融口座において、特定された Customer
に支払われた最新 5 件の OutboundPayment
オブジェクト を取得します。
OutboundPayment の状態
以下の表は、各ステータスと可能な移行状態について説明したものです。
ステータス | 説明 | 可能な状態の移行 |
---|---|---|
processing | OutboundPayment の開始状態。資金は、保留中の取引に割り当てられます (ただし、引き続き現在の残高に含まれています)。cancelable パラメーターの値が true の間は 、ユーザーは OutboundPayment をキャンセルできます。 | posted 、canceled 、failed |
failed (最終状態) | OutboundPayment の確認に失敗しました。Stripe は保留中の取引を無効にし、資金をユーザーに返金します。 | 該当なし |
canceled (最終状態) | ユーザーが、転記前に OutboundPayment をキャンセルしました。Stripe は、保留中の取引を無効にし、資金をユーザーに返金します。 | 該当なし |
posted | OutboundPayment が転記され、資金がアカウントから送金されました。基となる取引が転記されます。 | returned |
returned (最終状態) | OutboundPayment は、送金先に正常に入金されませんでした。資金は取引 (returned_details[transaction] ) とともにユーザーに返されます。 | 該当なし |
OutboundPayment をテストする
組み込みをエンドツーエンドでテストするには、テスト環境で SetupIntent リクエストを使用して PaymentMethod
を作成し、次に destination_payment_method
パラメーターを使用してその PaymentMethod
を OutboundPayment
作成リクエストに渡すことをお勧めします。
Stripe では、以下のようなテスト用の PaymentMethod
トークンおよび番号を使用して、特定の機能をトリガーすることもできます。
- テスト用の
PaymentMethod
トークンをdestination_payment_method
に渡す (ach
およびus_domestic_wire
のネットワークの場合)- テスト用の
PaymentMethod
トークンをdestination_payment_method
に直接渡す場合でも、顧客 ID をcustomer
パラメーターに渡す必要があります。便宜上このシナリオでは、既存のテスト環境のあらゆる顧客を渡すことができるようにしています。これは、本番環境とは異なります。本番環境では、既存のPaymentMethod
をCustomer
に関連付けて、その同じ顧客の ID をcustomer
パラメーターに渡す必要があります。
- テスト用の
- テスト用の金融番号と口座番号を
destination_payment_method_data[us_bank_account]
に渡す (ach
およびus_domestic_wire
のネットワークの場合)。 - プラットフォーム内のアカウントが保有する既存のテスト環境の金融口座の ID を
destination_payment_method_data[financial_account]
に渡す (Stripe ネットワークの場合)。
いずれの場合も、OutboundPayment
のレスポンスは処理中のステータスを返します。Stripe は、該当する状態の移行に対して Webhook をトリガーします。OutboundPayment
を作成後に取得すると、想定された状態が返されます。
作成 | DESTINATION_PAYMENT_METHOD (あらゆる既存のテスト環境用の顧客で) | DESTINATION_PAYMENT_METHOD_DATA[US_BANK_ACCOUNT] |
---|---|---|
初期の処理状態の OutboundPayment | pm_usBankAccount_processing |
|
(processing から) posted に移行する OutboundPayment | pm_usBankAccount |
|
(processing から) posted に移行する OutboundPayment 。さらに、元の expected_arrival_date に 1 日追加します | pm_usBankAccount_expectedArrivalDateUpdated |
|
(processing から) canceled に移行する OutboundPayment | pm_usBankAccount_canceledByUser |
|
(processing から) failed に移行する OutboundPayment | pm_usBankAccount_internalFailure |
|
アカウント閉鎖のために (転記後に processing から) returned に移行する OutboundPayment | pm_usBankAccount_accountClosed |
|
口座がないために (転記後に processing から) returned に移行する OutboundPayment | pm_usBankAccount_noAccount |
|
口座番号が無効であるために (転記後に processing から) returned に移行する OutboundPayment | pm_usBankAccount_invalidAccountNumber |
|
OutboundPayment のテスト用ヘルパーエンドポイント
Stripe は、さまざまな状態の OutboundPayments
をテストできるエンドポイントを提供しています。テストエンドポイントを使用して、作成した OutboundPayment
を posted
、failed
、または returned
などの新しい状態に直接移行します。
テスト用の post エンドポイントを使用して、特定された
OutboundPayment
をprocessing
からposted
に移行します。POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/post
テスト用の fail エンドポイントを使用して、特定された
OutboundPayment
をprocessing
からfailed
に移行します。POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/fail
テスト用の return エンドポイントを使用して、特定された
OutboundPayment
をprocessing
からreturned
に移行します。POST /v1/test_helpers/treasury/outbound_payments/{{OUTBOUND_PAYMENT_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 Payment
における追跡の詳細情報の送信をシミュレーションできます。tracking_details
フィールドは、テスト環境のオブジェクトに対してのみ設定できます。
いずれのケースでも、Stripe は、該当するそれぞれの状態の移行に対して Webhooks をトリガーします。移行後に OutboundPayment
を取得すると、想定される状態が返されます。
OutboundPayment の Webhook
Stripe は、Webhook エンドポイントに以下の OutboundPayment
イベントを送信します。
OutboundPayment
作成時のtreasury.outbound_payment.created
。OutboundPayment
のステータスが変化した際のtreasury.outbound_payment.{{new_status}}
。ステータス値のオプションには以下が含まれます。treasury.outbound_payment.posted
treasury.outbound_payment.failed
treasury.outbound_payment.canceled
treasury.outbound_payment.returned
OutboundPayment
のexpected_arrival_date
が変化した際のtreasury.outbound_payment.expected_arrival_date_updated
。OutboundPayment
の追跡の詳細情報が更新された際のtreasury.outbound_payment.tracking_details_updated
。