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

OutboundPayment objects represent push-based transfers from your financial account to a third-party external account using ACH or wire transfer, or another financial account associated with the same platform instantly using the stripe network. For example, if you want to send money from your financial account to your vendor’s external US bank account, you create an OutboundPayment to move the funds. The receiving accounts for an OutboundPayment are either an external bank account or another financial account.

The typical transfer time for outbound payments can range from minutes (when using the Stripe network), same day, to 1-2 business days (when using the ACH network). For more information, see the Money movement timelines guide.

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 の情報を追加します。

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d amount=2000 \
  -d currency=usd \
  -d statement_descriptor=payment_1 \
  -d "destination_payment_method_data[type]"=us_bank_account \
  -d "destination_payment_method_data[us_bank_account][account_holder_type]"=individual \
  -d "destination_payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "destination_payment_method_data[us_bank_account][account_number]"=1234567890 \
  --data-urlencode "destination_payment_method_data[billing_details][email]"="jenny@example.com" \
  -d "destination_payment_method_data[billing_details][phone]"=7135551212 \
  -d "destination_payment_method_data[billing_details][address][city]"=Alvin \
  -d "destination_payment_method_data[billing_details][address][state]"=TX \
  -d "destination_payment_method_data[billing_details][address][postal_code]"=77511 \
  -d "destination_payment_method_data[billing_details][address][line1]"="123 Main St." \
  -d "destination_payment_method_data[billing_details][name]"="Jenny Rosen"

成功すると、新しく作成された OutboundPayment がレスポンスで返されます。

{
  "id": "{{OUTBOUND_PAYMENT_ID}}",
  "object": "outbound_payment",
  // The source FinancialAccount. Funds are pulled from this account.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to send. 10.00 USD in this case.
  "amount": 1000,
  "cancelable": true | false,
  "currency": "usd",
  // The destination payment method. Either this or `destination_payment_method_data`

同日の ACH

Using same-day ACH enables sending funds that arrive the same business day if the OutboundPayment 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 に不完全なフィールドがある状態で電信送金しようとすると、エラーが発生します。

金融口座への OutboundPayment を作成する

To move money between financial accounts, call POST /v1/treasury/outbound_payments on the origin account and specify the destination account in the destination_payment_method_data parameter. Both financial accounts must be associated with the same platform, but can’t be associated with the same connected account. To transfer money between financial accounts associated with the same connected account, use an OutboundTransfer.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account={{SOURCE_FINANCIAL_ACCOUNT_ID}} \
  -d amount=2000 \
  -d currency=usd \
  -d statement_descriptor="Test outbound payment to FA" \
  -d "destination_payment_method_data[type]"=financial_account \
  -d "destination_payment_method_data[financial_account]"={{DESTINATION_FINANCIAL_ACCOUNT_ID}}

リクエストの本文は、x-www-form-urlencoded でなければなりませんが、以下の JSON は、送信できるデータを定義します。

{
  // The source FinancialAccount. Funds are pulled from this account.
  "financial_account": "{{SOURCE_FINANCIAL_ACCOUNT_ID}}",
  // The amount to send.
  "amount": 1000,
  "currency": "usd",
  // The destination payment method. This parameter is the only way to
  // send an OutboundPayment through the `stripe` network.
  "destination_payment_method_data": {
    "type": "financial_account",

OutboundPayment を取得する

GET /v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}} を使用し、関連付けられた ID の OutboundPayment の詳細を取得します。

curl https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

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

{
  "id": "{{OUTBOUND_PAYMENT_ID}}",
  "object": "outbound_payment",
  "livemode": true | false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  // Will only be set if `destination_payment_method` was used during the creation of
  // the OutboundPayment

OutboundPayment をキャンセルする

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

curl -X POST https://api.stripe.com/v1/treasury/outbound_payments/{{OUTBOUND_PAYMENT_ID}}/cancel \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

成功すると、レスポンスで、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 オブジェクト を取得します。

curl -G https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d limit=5 \
  -d customer=
{{CUSTOMER_ID}}

OutboundPayment の状態

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

OutboundPayment をテストする

To test your integration end-to-end, we recommend using test SetupIntent requests to create a PaymentMethod, then passing that PaymentMethod into an OutboundPayment creation request using the destination_payment_method parameter.

Stripe では、以下のようなテスト用の PaymentMethod トークンおよび番号を使用して、特定の機能をトリガーすることもできます。

• テスト用の PaymentMethod トークンを destination_payment_method に渡す (ach および us_domestic_wire のネットワークの場合)
  • テスト用の PaymentMethod トークンを destination_payment_method に直接渡す場合でも、customer パラメーターに顧客 ID を渡す必要があります。便宜上、Stripe では既存のテスト用顧客を渡すことができます。これは、既存の 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 を作成後に取得すると、想定された状態が返されます。

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"
  }
}

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