コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン
概要
事業で活用する
即時通貨換算
プラットフォームに組み込む
Financial Accounts for platforms

注

このページはまだ日本語ではご利用いただけません。より多くの言語で文書が閲覧できるように現在取り組んでいます。準備が整い次第、翻訳版を提供いたしますので、もう少しお待ちください。

Treasury を使用して資金を移動する

SetupIntents、PaymentMethods を使用して、Stripe Treasury で銀行口座を確認する方法をご紹介します。

Homebox is a fictitious vertical SaaS that builds software for home services companies such as HVAC, cleaners, and plumbers. This example integration describes some basic money movement using the treasury endpoints of the Stripe API. To see how the company would set up a financial account and issue payment cards, see Using Financial Accounts for platforms to set up financial accounts and cards.

外部の銀行口座の使用

Financial Accounts for platforms provides platforms with a suite of account creation and money movement API endpoints to help store, manage, and move connected account funds. Platforms can fund a financial account, and move money between financial accounts and external bank accounts.

The Stripe API provides InboundTransfer and OutboundTransfer to facilitate moving money between connected accounts’ external bank accounts and their financial accounts. The Stripe API also provides OutboundPayment to facilitate moving money from connected accounts’ financial accounts to third-party external bank accounts. All of these objects can use PaymentMethods to store external bank account details such as routing numbers and account numbers.

PaymentMethods の説明

Stripe API では、PaymentMethod オブジェクトを使用して、支払い方法の情報を保存できます。たとえば、Homebox は、ベンダーのアカウントを PaymentMethods として保存すると、情報を再入力して収集する必要なしに、資金を送金できます。

You can attach PaymentMethods that contain external bank account information to a customer (for sending money to a third party) or to a Stripe account (for pulling money from or sending money to an external bank account belonging to the Stripe accountholder). The “customer” refers to the Customer object in the Stripe API, which defines any third party. In Financial Accounts for platforms usage, the customer is generally a vendor receiving payments from the Stripe accountholder rather than making payments to the Stripe accountholder. Use the SetupIntent object to set up both customer-attached and account-attached PaymentMethod objects.

PaymentMethod で使用できる関連 API オブジェクトは、その関連付けの方法によって異なります。

  • 顧客に関連付け: OutboundPayments を使用します。
  • アカウントに関連付け: InboundTransfers および OutboundTransfers を使用します。
フローチャート。左側の外部銀行口座からの矢印が SetupIntent、さらに PaymentMethod につながり、顧客またはアカウントに関連付けられている。

PaymentMethod のフロー

InboundTransfers および OutboundTransfers の概要

InboundTransfer を使用して Stripe アカウントの外部銀行口座から資金を引き出し、OutboundTransfer を使用して同じ所有者の外部銀行口座に資金を追加できます。

To successfully pull funds into a financial account with an InboundTransfer, external bank accounts must be verified by the Stripe accountholder. Bank accounts that are used to send funds out of a financial account with an OutboundTransfer don’t need to be verified.

外部の銀行口座が InboundTransfers または OutboundTransfers に使用される場合、対応する PaymentMethod を Stripe アカウント (顧客ではなく) にアタッチする必要があります。これを行うには、SetupIntent を使用して PaymentMethod を作成するときに、customer パラメーターではなく、attach_to_self=true パラメーターを使用します。

フローチャート。左側の外部銀行口座からの矢印が SetupIntent、さらに PaymentMethod につながり、Stripe アカウントに関連付けられている。

InboundTransfers および OutboundTransfers のフロー。

OutboundPayments

Platforms use the OutboundPayment API to send funds from a financial account to an external bank account owned by a third party.

OutboundPayments で使用するには、PaymentMethods を顧客にアタッチする必要があります。OutboundPayments に使用する銀行口座を確認する必要はありません。

OutboundPayments のフロー

外部の銀行口座を追加

Homebox wants to link their customers’ own external bank accounts to their financial accounts. The Homebox connected accounts want to keep all of their business capital in their financial accounts and use inbound transfers to pull money from their external account into their financial account. To enable their connected accounts to transfer money to and from their external accounts, Homebox creates a SetupIntent with the required parameters and attaches it to an account-attached PaymentMethod:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d attach_to_self=true \
  -d "flow_directions[]"=inbound \
  -d "flow_directions[]"=outbound \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_data[type]"=us_bank_account \
  -d "payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "payment_method_data[us_bank_account][account_number]"=000123456789 \
  -d "payment_method_data[us_bank_account][account_holder_type]"=company \
  -d "payment_method_data[billing_details][name]"="Company Corp" \
  -d confirm=true \
  -d "mandate_data[customer_acceptance][type]"=online \
  -d "mandate_data[customer_acceptance][online][ip_address]"="123.123.123.123" \
  --data-urlencode "mandate_data[customer_acceptance][online][user_agent]"="curl/1.2.3"

OutboundTransfers または InboundTransfers を使用して資金の送受金を行うために、Homebox は、payment_method_data[us_bank_account] パラメーターで外部の銀行口座を指定する必要があります。本番環境の外部銀行口座リンクを作成する前に、Homebox は、Stripe が提供するテスト用口座番号を使用してフローをテストします。

上記の例のように、Homebox は、外部の銀行口座 (payment_method_data[us_bank_account]) を定義して、attach_to_self を true に設定しました。これにより、銀行口座情報を Stripe アカウント所有者 (サードパーティーではない) に関連付けることができます。プラットフォームがリクエストを送信すると、API は SetupIntent で応答します。

{
  "id": "{{SETUP_INTENT_ID}}",
  "object": "setup_intent",
  "application": "{{APPLICATION_ID}}",
  "attach_to_self": true,
  "cancellation_reason": null,
  "client_secret": "{{SETUP_INTENT_SECRET}}",
  "created": 1642520861,
  "customer": null,
  "description": null,
  "flow_directions": [
    "inbound",
    "outbound"
  ],
  "last_setup_error": null,
  "latest_attempt": "{{ATTEMPT_ID}}",
  "livemode": false,
  "mandate": "{{MANDATE_ID}}",
  "metadata": {
  },
  "next_action": {
    "type": "verify_with_microdeposits",
    "verify_with_microdeposits": {
      "arrival_date": 1642579200,
      "hosted_verification_url": "https://payments.stripe.com/microdeposit/sacs_test_xxx",
      "microdeposit_type": "amounts"
    }
  },
  "on_behalf_of": null,
  "payment_method": "{{PAYMENT_METHOD_ID}}",
  "payment_method_options": {
    "us_bank_account": {
      "verification_method": "automatic"
    }
  },
  "payment_method_types": [
    "us_bank_account"
  ],
  "single_use_mandate": null,
  "status": "requires_confirmation",
  "usage": "off_session"
}

外部の銀行口座の確認

前のセクションで、Homebox は外部の銀行口座をリンクしました。この銀行口座を Homebox が InboundTransfers で使用するには、事前の確認が必要です。銀行口座を確認することで、アカウント所有者は外部の銀行口座の名義人を確認できます。Homebox は、Stripe Financial Connections で即時に確認することも、少額入金 (より時間がかかります) で確認することもできます。

Stripe Financial Connections

Financial Connections を使用して、所有する銀行口座を即時に確認できます。Financial Connections は、Stripe がホストするフローであり、アプリケーションのクライアント側とサーバー側に実装されます。

Homebox が Financial Connections で銀行口座情報を収集して確認するために必要な 3 つのステップ:

  1. customer_id プロパティーの代わりに attach_to_self プロパティーを指定し、verification_method プロパティーの値に instantを指定して SetupIntent を作成します。

  2. フロントエンドアプリケーションに client_secret を提供して stripe.collectBankAccountForSetup を使用し、銀行口座の詳細を収集し、PaymentMethod を作成して、PaymentMethod を SetupIntent にアタッチします。

    注

    billing_details パラメーターのアカウント所有者の名前は、アメリカの銀行口座のPaymentMethod を作成するために必要です。

  3. 同意書の規約を表示して、PaymentMethod を使用する許可を収集うします。

ステップ 1 では、Homebox は以下のコードを生成してサーバー側で SetupIntent を作成し、handlebars.js テンプレートに情報を渡します。このコードは、アプリケーションには Stripe にログインしているユーザーがいて、Stripe アカウント ID を Session オブジェクト (req.session.accountId) の一部として渡すことを想定します。

const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);
router.get('/add_bank_account', async (req, res) => {
  const account = await stripe.accounts.retrieve(req.session.accountId);
  const setupIntent = await stripe.setupIntents.create({
    attach_to_self: true,
    flow_directions: ['inbound', 'outbound'],
    payment_method_types: ['us_bank_account'],
    payment_method_options: {us_bank_account: {verification_method: "automatic"}}
  },{
    stripeAccount: account.id,
  });
  let client_secret= setupIntent.client_secret;
  res.render('add_bank_account', { account: account, client_secret: client_secret, stripe_pk: process.env.STRIPE_PUBLISHABLE_KEY });
});

ステップ 2 は、Homebox が以下のデータを render 関数に渡すと開始します。

  • Stripe アカウント ID。
  • ID として使用される SetupIntent から取得した client secret。
  • プラットフォームの公開可能な API キー。

この例では、クライアント側のページに、Financial Connections を使用して銀行口座を確認するためのボタンがレンダリングされます。

「銀行口座を追加する」モーダルのスクリーンショットに、「支払い情報の保存」ボタンを表示。

銀行口座を追加するためのモーダル

Homebox は、前述のボタンの背後にあるロジックを動作させるために、以下のコードを作成します。

const getBankAccount = async e => {
  paymentMethodButton.setAttribute("disabled", "disabled");
  // Calling this method triggers the Financial Connections modal to display.
  const response = await stripe.collectBankAccountForSetup("{{ client_secret }}", {
    billing_details: {
      name: "John Doe",
      email: "test@test.com",
    },
  });
  if (response.error)
  {
    console.error(response.error);
  }
  if (response.status == "requires_confirmation")
  {
    //Show confirmation modal
    AcceptBankAccountModal.classList.remove("hidden");
  }
};

このコード例では、スクリプトは collectUsBankAccountForSetup メソッドを呼び出し、SetupIntent から取得した client_secret を渡します。アプリケーションのダイアログは、銀行口座をリンクする手順をユーザーに示します。

銀行口座を追加するワークフローを実行中のモーダルのスクリーンショット。モーダルの最初の段階では「同意する」ボタンでの承認ステップ、次の段階では口座を関連付けるためのボタンを表示し、口座を強調表示。

銀行口座を追加するためのワークフロー

ステップ 3 は、SetupIntent ステータスが requires_confirmation に変更され、モーダルにユーザーの確認用の承認メッセージが表示されて、先行のワークフローが正常に完了すると開始されます。

承認の確定に関する文言が表示されているモーダルのスクリーンショット。下部には「同意する」ボタン、左上にはキャンセルするための x を表示。

承認メッセージ

ユーザーが同意するをクリックすると、コードは confirmUsBankAccountSetup メソッドを呼び出し、銀行口座が確認済みとして保管されます。これで、銀行口座を InboundTransfers に使用できます。

const acceptBankAccount = async e => {
  acceptButton.setAttribute("disabled", "disabled");
  const response = await stripe.confirmUsBankAccountSetup("{{ client_secret }}");
  if (response.setupIntent.status == "requires_payment_method") {
    // Confirmation failed. Attempt again with a different payment method.
    console.log("Requires payment method")
  } else if (response.setupIntent.status == "succeeded") {
    // Confirmation succeeded! The account is now saved.
    // Display a message to customer.
    AcceptBankAccountModal.classList.add("hidden");
    console.log("Account added");
  } else if (response.setupIntent.next_action?.type == "verify_with_microdeposits") {
    // The account needs to be verified through microdeposits.
    // Display a message to consumer with next steps (consumer waits for
    // microdeposits, then enters an amount on a page sent to them through email).
    console.log("The account needs to be verified with microdeposits")
  }
};

少額入金

少額入金は、Stripe が外部の銀行口座に入金する少額 (通常は本の少額の USD) の資金です。口座の所有者は、こうした入金の正確な金額を確認することにより、口座の所有権を確認できます。

Homebox が前のセクションで作成した SetupIntent オブジェクトには、PaymentMethod ID が含まれています。

{
  "id": "{{SETUP_INTENT_ID}}",
  …
  "on_behalf_of": null,
  "payment_method": "{{PAYMENT_METHOD_ID}}",
  "payment_method_options": {
…
 }
}

SetupIntent には、hosted_verification_url 値で URL が定義された next_action オブジェクトも含まれています。

{
  "id": "{{SETUP_INTENT_ID}}",
…
   "next_action": {
    "type": "verify_with_microdeposits",
    "verify_with_microdeposits": {
      "arrival_date": 1642579200,
      "hosted_verification_url": "https://payments.stripe.com/microdeposit/sacs_test_xxx",
      "microdeposit_type": "amounts"
    }
…
 }

Homebox は、確認を完了するために、連結アカウントの所有者に URL を提供します。所有者は URL をたどり、対象の少額入金の記述子コード (テスト環境では、値 SM11AA を使用) を入力して受領を確認する必要があります。

アカウントへの 1 セントの入金を示す、少額入金の確認ダイアログで、明細書表記コードの入力と確認ボタンのクリックを促す表示。

少額入金確認

PaymentMethods を InboundTransfers で使用する

Homebox では、前述のいずれかの方法で確認済みの銀行口座を使用して InboundTransfers の作成を開始できます。

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/treasury/inbound_transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 が含まれ、Homeboxプラットフォームのアカウント所有者が取引詳細にアクセスできるようにします。

{
    "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",
    ...
}

PaymentMethods を OutboundPayments で使用する

また PaymentMethod を使用し、OutboundPayment オブジェクトを使用して、サードパーティーが保有する外部の銀行口座に資金を送金することもできます。

Homebox は、用品に対する支払いのために、連結アカウントのベンダー 1 社に継続的に送金する必要があります。そのためには、プラットフォームは、最初に Customers エンドポイントを使用して顧客 ID を取得する必要があります。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d description="Test Customer"

レスポンスには、関連する連結アカウントの顧客が示されます。Homebox は、適正な顧客を確認して、ID を記録します。

{
  "id": "{{CUSTOMER_ID}}",
  "object": "customer",
  "address": null,
  "balance": 0,
  "created": 1642523420,
  "currency": null,
  "default_source": null,
  "delinquent": false,
  "description": "Test Customer",
  "discount": null,
  "email": null,
  "invoice_prefix": "96A50A92",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null
  },
  "livemode": false,
  "metadata": {
  },
  "name": null,
  "next_invoice_sequence": 1,
  "phone": null,
  "preferred_locales": [

  ],
  "shipping": null,
  "tax_exempt": "none"
}

次に、Homebox は、ID を使用して SetupIntent を作成します。サードパーティーへのアウトバウンドの資金のフローでは OutboundPayments が使用されるため、Homebox は customer を指定する代わりに flow_directions を outbound に設定し、attach_to_self を使用する必要があります。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "flow_directions[]"=outbound \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_data[type]"=us_bank_account \
  -d "payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "payment_method_data[us_bank_account][account_number]"=000123456789 \
  -d "payment_method_data[us_bank_account][account_holder_type]"=individual \
  -d "payment_method_data[billing_details][name]"="John doe" \
  -d confirm=true

呼び出しが成功すると、PaymentMethod が顧客に正常に関連付けられたことを示す次のオブジェクトが返されます。

{
  "id": "{{SETUP_INTENT_ID}}",
  "object": "setup_intent",
  "application": "{{APPLICATION_ID}}",
  "cancellation_reason": null,
  "client_secret": "{{SETUP_INTENT_SECRET}}",
  "created": 1642528487,
  "customer": "{{CUSTOMER_ID}}",
  "description": null,
  "flow_directions": [
    "outbound"
  ],
  "last_setup_error": null,
  "latest_attempt": null,
  "livemode": false,
  "mandate": null,
  "metadata": {
  },
  "next_action": null,
  "on_behalf_of": null,
  "payment_method": "{{PAYMENT_METHOD_ID}}",
  "payment_method_options": {
  },
  "payment_method_types": [
    "us_bank_account"
  ],
  "single_use_mandate": null,
  "status": "succeeded",
  "usage": "off_session"
}

PaymentMethod なしで OutboundPayment を作成する

1 回限りの支払いと同様に受取人の銀行口座を保存する必要がない場合、OutboundPayments を送信または使用するときに PaymentMethods は必要ありません。

Homebox は、消耗品の費用として 50 USD をベンダーに支払う必要がありました。ベンダーに支払うために、プラットフォームは、外部銀行口座情報を指定して OutboundPayments を呼び出します。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "destination_payment_method_data[type]"=us_bank_account \
  -d "destination_payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "destination_payment_method_data[us_bank_account][account_number]"=000123456789 \
  -d "destination_payment_method_data[us_bank_account][account_holder_type]"=individual \
  -d "destination_payment_method_data[billing_details][name]"="John Doe" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}}
 \
  -d statement_descriptor=payment_1 \
  -d amount=5000 \
  -d currency=usd

呼び出しが成功すると、次のオブジェクトが返されます。

{
  "id": "{{OUTBOUNDPAYMENT_ID}}",
  "object": "treasury.outbound_payment",
  "amount": 5000,
  "cancelable": true,
  "created": 1643033124,
  "currency": "usd",
  "customer": null,
  "description": null,
  "destination_payment_method": null,
  "destination_payment_method_details": {
    "billing_details": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": null,
      "name": "John Doe",
      "phone": null
    },
    "type": "us_bank_account",
    "us_bank_account": {
      "account_holder_type": "individual",
      "bank_name": "STRIPE TEST BANK",
      "fingerprint": "SzrMIps1gg91aVKG",
      "last4": "6789",
      "network": "ach",
      "routing_number": "110000000"
    }
  },
  "end_user_details": {
    "present": false,
    "ip_address": null
  },
  "expected_arrival_date": 1643068800,
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/bot_test_xxx",
  "livemode": false,
  "metadata": {
  },
  "statement_descriptor": "payment_1",
  "status": "processing",
  "status_transitions": {
    "canceled_at": null,
    "failed_at": null,
    "posted_at": null,
    "processing_at": 1643033124,
    "returned_at": null
  },
  "transaction": "{{TRANSACTION_ID}}"
}

参照情報

このページはお役に立ちましたか。
はいいいえ