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

POST /v1/treasury/inbound_transfers を使用して InboundTransfer オブジェクトを作成します。これは、お客様が保有する外部口座から自身の金融口座への引き出しベースの送金を表します。言い換えると、InboundTransfer を作成し、外部のアメリカの銀行口座から引き落としを行い、金融口座に資金を移動します。このリクエストには、以下のパラメーターを含める必要があります。

• amount: 金融口座に送金されるセント単位での金額。
• currency: 3 文字の ISO 通貨コード (サポートされている値は、現在 usd のみ)。
• financial_account: 送金を受け取る金融口座の ID。
• origin_payment_method: インバウンド送金の送金元。まず、SetupIntent(支払い方法設定インテント) を使用して、アカウントに関連付けられたインバウンドフローの支払い方法を設定し、銀行口座を確認する必要があります。別の方法として、確認済みの ExternalAccount (外部銀行口座) として以前に設定された既存の BankAccount (銀行口座) を使用することもできます。支払い方法と銀行口座のいずれを使用する場合でも、口座から資金を引き落とすには、口座名義人の許可が必要です。

以下の JSON は、リクエストの本文に含めることができるデータを示します。

{
  // The source PaymentMethod or BankAccount. Funds are pulled from this account.
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}" | "{{BANK_ACCOUNT_ID}}",
  // The destination FinancialAccount. Funds arrive in this account.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to debit. 10.00 USD in this case.
  "amount": 1000,
  "currency": "usd",
  // An optional, internal description for the InboundTransfer.
  "description": "Funds for vendor payment payment_234281",
  // An optional descriptor for the InboundTransfer to send
  // to the network with the debit request. Max 10 characters
  "statement_descriptor": "payment_1",
  // Stripe does not support updating InboundTransfers after creation.
  // You can only set metadata at creation time.
  "metadata": null | {{Hash}}
}

以下のリクエストは、アカウントに関連付けられた支払い方法を使用して 200 USD を指定された ID の金融口座に送金します。Stripe-Account ヘッダー値は、金融アカウントと支払い方法の両方を所有する Stripe アカウントを識別します。

curl https://api.stripe.com/v1/treasury/inbound_transfers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d origin_payment_method=
{{PAYMENT_METHOD_ID}} \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d amount=20000 \
  -d currency=usd \
  -d description="Funds for repair" \
  -d statement_descriptor="Invoice 12"

成功すると、レスポンスで InboundTransfer オブジェクトが提供されます。このオブジェクトには、hosted_regulatory_receipt_url が含まれ、お客様のプラットフォームのアカウント所有者が取引詳細にアクセスできるようにします。

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Funds for repair",
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{IBT_URL}}",
    "linked_flows": null,
    "livemode": false,
    "metadata": {},
    "origin_payment_method": "{{PAYMENT_METHOD_ID}}",
    ...
    "statement_descriptor": "Invoice 12",
    "status": "processing",
    ...
}

同日の ACH

同日の ACH を使用すると、カットオフ時間 までに InboundTransfer コールが正常に完了した場合、同一営業日内に元の金融口座に売上を入金できます。 同日の ACH を使用するには、origin_payment_method_options.us_bank_account.ach.submission パラメーターを same_day に設定します。

GET /v1/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}} を使用し、関連付けられた ID の InboundTransfer オブジェクトを取得します。

以下の JSON は、リクエストの本文に含めることができるデータを示します。 レスポンスの一部のパラメーターには、expand[] パラメーターに値として追加した場合にのみ返される追加情報があります。次のレスポンス例で、拡張できるフィールドには、「Expandable」コメントが付いています。オブジェクトレスポンスの拡張の詳細については、レスポンスを拡張するをご覧ください。

{
  "id": "{{INBOUND_TRANSFER_ID}}",
  "object": "inbound_transfer",
  "livemode": false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  // The only current valid PaymentMethod type for InboundTransfers is us_bank_account
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}",

次のリクエストは、id 値が {{INBOUND_TRANSFER_ID}} の InboundTransfer を取得します。本文の expand[] 配列に transaction を含めると、該当する情報が展開されて返されます。

curl -G https://api.stripe.com/v1/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "expand[]"=financial_account

成功すると、拡張された情報を持つ InboundTransfer オブジェクトがレスポンスで返されます。

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Inbound transfer",
    "failure_details": null,
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{INBOUND_TRANSFER_ID}}",

GET /v1/treasury/inbound_transfers を使用し、関連付けられた ID の金融口座のすべての InboundTransfers を取得します。標準のリストパラメーターまたは status でリストをフィルタリングできます。

{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by status
  "status": "processing" | "succeeded" | "failed",
  // Filter by FinancialAccount (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Required
}

以下のリクエストは、ID {{CONNECTED_ACCOUNT_ID}} の連結アカウントに関連付けらた、ID {{FINANCIAL_ACCOUNT_ID}} の金融口座について、ステータスが succeeded のインバウンド送金をすべて取得します。

curl -G https://api.stripe.com/v1/treasury/inbound_transfers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d status=succeeded

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

導入をエンドツーエンドでテストするには、テスト環境で SetupIntents リクエストを使用して PaymentMethod を作成します。次に、その PaymentMethod を InboundTransfer 作成リクエストに渡します。PaymentMethods が有効な場合は InboundTransfers が成功し、PaymentMethods が無効な場合 (サポートされていないタイプの場合、未確認の銀行口座が含まれる場合、インバウンドフロー用に設定されていない場合など) には、本番環境と同じエラーが発生します。

Stripe では、テスト用の PaymentMethod トークンのセットも用意しています。これを使用すると、次のような特定の状態の移行をトリガーできます。

さまざまなエッジケースをより迅速にテストするために、PaymentMethod のトークンは以下の特定の失敗タイプをシミュレーションします。

いずれの場合も、InboundTransfer のレスポンスは processing 状態で始まります。関連する状態の移行ごとに Webhooks を受信し、InboundTransfer を作成後に取得すると、想定された状態が返されます。

Stripe では、さまざまな状態の InboundTransfers をテストできるエンドポイントも提供しています。InboundTransfer を作成し、以下の手順に従います。

• テスト用の succeed エンドポイント を使用し、関連付けられた ID の送金を直接 succeeded 状態に移行します。

  POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/succeed

• テスト用の fail エンドポイント を使用し、関連付けられた ID の送金を直接 failed の状態に移行します。

  POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/fail

これらのエンドポイントは、返品などのエラーシナリオをテストするために特に便利です。こういったエンドポイントがなければ、InboundTransfer が資金を引き出していた外部の口座からのアクションが必要になります。

本文にオプションの failure_details.code パラメーターを含め、送金が失敗した理由を示します。この情報が提供されない場合には、送金はデフォルトの could_not_process 失敗コードで失敗します。

{
  "failure_details": {
    "code": "account_closed" |
          "account_frozen" |
          "bank_account_restricted" |
          "bank_ownership_changed" |
          "could_not_process" | // Generic fallback code
          "invalid_account_number" |
          "incorrect_account_holder_name" |
          "invalid_currency" |
          "no_account"
  }
}

Treasury は、成功した後で返金される InboundTransfer をシミュレーションするための return エンドポイントも提供しています。

テスト用の return エンドポイント を使用し、関連付けられた ID の InboundTransfer で返金のシミュレーションを開始します。

POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/return

すべてのテスト用エンドポイントは、該当するそれぞれの状態の移行に対して Webhooks をトリガーします。移行後に InboundTransfer を取得すると、想定される状態が返されます。

Stripe は、Webhook エンドポイントに以下の InboundTransfer イベントを送信します。

• InboundTransfer 作成時の treasury.inbound_transfer.created。
• InboundTransfer のステータスが変化した際の treasury.inbound_transfer.{{new_status}}。ステータス値のオプションには以下が含まれます。
  • treasury.inbound_transfer.succeeded
  • treasury.inbound_transfer.failed