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

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 ネットワーク経由の別の金融口座への送金に使用できます。

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

同日の ACH を使用すると、カットオフ時間 までに OutboundPayment コールが正常に完了した場合、同一営業日内に到着する売上を送信できます。 同日の 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 に不完全なフィールドがある状態で電信送金しようとすると、エラーが発生します。

金融口座間で資金を移動するには、移動元口座で POST /v1/treasury/outbound_payments を呼び出し、destination_payment_method_data パラメーターで移動先口座を指定します。両方の金融口座を同じプラットフォームに関連付ける必要がありますが、関連付ける先は連結アカウントとプラットフォームのいずれかにできます。

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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 via the `stripe` network.
  "destination_payment_method_data": {
    "type": "financial_account",

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -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",

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_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d limit=5 \
  -d customer=
{{CUSTOMER_ID}}

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

導入をエンドツーエンドでテストするには、テスト環境で 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 を作成後に取得すると、想定された状態が返されます。

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 を取得すると、想定される状態が返されます。

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。