# カスタムの Capital プログラムを構築する

API を実装してカスタムの Capital プログラムを構築します。

[Stripe Capital](https://docs.stripe.com/capital/how-capital-for-platforms-works.md) を使用すると、プラットフォームで連結アカウントの事前適格融資オファーを取得し、準拠した融資オファーアプリケーションを公開し、進行中の融資に関する継続的なレポートを提供できます。

このガイドでは、[Connect](https://docs.stripe.com/connect.md) プラットフォームを [Capital API](https://docs.stripe.com/api/capital/financing_offers.md) と連携してオファーメールを送信し、レポートを管理する方法について説明します。オファーメールを送信する際は、すべてのメールで [capital-offers@stripe.com](mailto:capital-offers@stripe.com) を BCC に含める必要があります。

### Capital のライフサイクル

このプログラムを開始するには、プラットフォームが Capital のライフサイクルの以下の 3 つのフェーズに対応可能である必要があります。

- オファーメール、[組み込みコンポーネント](https://docs.stripe.com/connect/supported-embedded-components/capital-financing-application.md)、またはその両方を通じて、対象となる連結アカウントに資金調達オファーを案内します。
- ホスト型ページ、[組み込みコンポーネント](https://docs.stripe.com/connect/supported-embedded-components/capital-financing.md)、API ベースのカスタムレポート、またはこれら 3 つの組み合わせを通じて、進行中の資金調達に関するレポートページへのアクセスを提供します。
- 連結アカウントが資金調達を完済した後も、引き続き資金調達レポートページへのアクセスを提供します。

このガイドでは、Capital API を利用して次のことを行う方法について説明します。

- 対象となる連結アカウントの資金調達オファーを取得します。
- 連結アカウントが資金調達の申し込みを利用できるようにします。
- 連結アカウントに資金調達レポートへのアクセスを提供します。

### 実装フェーズ

1. **始める前に:** プラットフォームのブランディング設定を確認し、テスト用のオファーを作成します。
2. **オファー配信フローを構築する:** オファーの取得、オファーメールの送信、アカウントリンクの作成または更新、オファーへの配信済みマークの付与を行います。
3. **資金調達ライフサイクルの更新を処理する:** Webhook、申し込み時に提出した内容の審査、資金調達の入金、支払い、資金調達レポート、返済を処理します。
4. **実装を検証してローンチする:** テストフローを確認し、自動オファーを有効にしてから、再融資とレポートを追加します。

## ブランディング設定を確認する [ダッシュボード]

Capital オファーを受け取るすべての連結アカウントには、オファーメール、申し込み、資金調達レポートページで、貴社のビジネス名、アイコン、ロゴ、ブランドカラーが表示されます。

\**[Connect ブランディング設定](https://dashboard.stripe.com/settings/connect/stripe-dashboard/branding)\**に移動し、プラットフォームのブランディング設定が正しいことを確認します。
![Capital オファーの申し込みページ](https://b.stripecdn.com/docs-statics-srv/assets/offer-page.66c647c99e2b25b314b7ca8be2cc98a4.png)

## 未提供のテスト用融資オファーを作成する [ダッシュボード]

システムを構築するにあたり、*サンドボックス* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)を使用することをお勧めします。サンドボックスで、[Capital ダッシュボード](https://dashboard.stripe.com/test/connect/capital)にアクセスします。

1. **作成**をクリックして**融資オファーの作成**モーダルを開き、テスト用融資オファーを作成できます。デフォルトのオプションでは、融資額 1,000 USD の未提供の融資オファーが作成されます。
2. デフォルトのオプションをそのままにして**融資オファーを作成**をクリックします。
3. ダッシュボードで、作成したオファーに対応する行をクリックします。

連結アカウント詳細ページのローンと資金調達セクションには、その連結アカウントの資金調達オファーの詳細が表示されます。

## 融資オファーを取得する [サーバー側]

[List financing offers (資金調達オファーの一覧表示)](https://docs.stripe.com/api/capital/financing_offers/list.md)エンドポイントを使用すると、プラットフォームのすべての連結アカウントの資金調達オファーを取得できます。

#### curl

```bash
curl https://api.stripe.com/v1/capital/financing_offers \
  -u <<YOUR_SECRET_KEY>>:
```

オファーが正常に作成されると、次のようなレスポンスが返されます。

```json
{
  "object": "list",
  "url": "/v1/capital/financing_offers",
  "has_more": false,
  "data": [
    {
      "id": "financingoffer_abc123",
      "object": "capital.financing_offer"
      ...
    },
    {...}
  ]
}
```

[Retrieve financing offer (融資オファーの取得)](https://docs.stripe.com/api/capital/financing_offers/retrieve.md#retrieve_financing_offer) エンドポイントを使用して、融資オファーを確認できます。上記の一覧から最初の融資オファーを取得します。

#### curl

```bash
curl https://api.stripe.com/v1/capital/financing_offers/financingoffer_abc123 \
  -u <<YOUR_SECRET_KEY>>:
```

## オファーメールを送信 [サーバー側]

### Webhook を使用してオファーの作成を処理する

自社の資金調達オファーメールを送信するには、Stripe が資金調達オファーを作成した後に送信する `capital.financing_offer.created` *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) をリッスンします。この Webhook を受け取ったら、直ちに連結アカウントにオファーメールを送信してください。

Capital Webhook イベントは、Connect Webhook としてではなく、アカウントから設定する必要があります。これらのイベントは連結アカウントに関するデータを伝送しますが、Stripe はプラットフォームアカウントで融資オファーを作成して管理します。[ダッシュボード](https://dashboard.stripe.com/webhooks)で Capital Webhook エンドポイントを設定するか、`connect` パラメーターを指定せずに [Webhook Endpoints API](https://docs.stripe.com/api/webhook_endpoints/create.md) を使用して Capital Webhook エンドポイントを設定し、連結アカウントのアクティビティをリッスンする Connect Webhook ではなく、プラットフォームアカウントの Webhook として登録します。

> [マーケティングガイダンス](https://docs.stripe.com/capital/marketing.md)ページを確認して、オファーメールの内容が銀行規制に準拠していることをご確認ください。審査と承認に必要なユーザーに表示される資料が変更された場合には[変更リクエストフォーム](https://form.asana.com/?k=8K51UWmWhttehNFD5qBLdg&d=974470123217835)を使用してすべての変更事項を提出してください。

### オファーメールの送信

メール内で、Capital ランディングページや Capital ダッシュボードなど、プラットフォームダッシュボード内の専用 Capital セクションに連結アカウントを誘導します。そのページで [アカウントリンク](https://docs.stripe.com/api/account_links.md) を使用して Capital の資金調達の申し込みを表示し、連結アカウントが Capital の申し込みにアクセスできるようにします。

### 資金調達の申し込み用のアカウントリンクの作成

アカウントリンクを生成して、プラットフォームダッシュボードに資金調達の申し込みへのリンクを含めます。`capital_financing_offer` タイプのアカウントリンクを生成して、Stripe がホストする申し込みページへの一時的なアクセスを提供できます。アカウントリンクは Stripe が生成した直後に期限切れになるため、必要に応じて生成するか、リダイレクトを使用して連結アカウントが申し込みリンクを再生成できるようにします。

### アカウントリンクの有効期限を処理する

オファーメールにアカウントリンクの URL を直接送信しないでください。受取人がメールを開く前にアカウントリンクが期限切れになる可能性があるためです。代わりに、プラットフォームでホストされている安定した URL(`https://yourplatform.com/capital/accept_offer` など)を含めます。リンクを以下のように設定してください。

1. 連結アカウントを認証します。
2. API を使用して新しいアカウントリンクを生成します。
3. 生成されたばかりのアカウントリンクの URL に連結アカウントをリダイレクトします。

このようにすると、連結アカウントがメールを開くタイミングに関係なく、常に新しく有効なアカウントリンクを受け取ることができます。

#### curl

```bash
curl https://api.stripe.com/v1/account_links \
  -u <<YOUR_SECRET_KEY>>: \
  -d account=acct_123 \
  # The URL the connected account will be redirected to if the account link is expired, has been previously-visited, or is otherwise invalid.
  -d refresh_url="https://example.com/reauth" \
  # The URL the connected account will be redirected to after completing the linked flow.
  -d return_url="https://example.com/thanks" \
  -d type=capital_financing_offer
```

Account Link が正常に作成されると、次のようなレスポンスが返されます。

```json
{
  "object": "account_link",
  "created": 1611264596,
  "expires_at": 1611264896,
  "url": "https://connect.stripe.com/capital/offer/SrjgLUfa0O7K"
}
```

Webhook の実装を更新した後に、[ダッシュボード](https://dashboard.stripe.com/test/connect/capital)で新たにオファーを作成し、`capital.financing_offer.created` Webhook が届くことを確認します。

### オファーを提供済みとしてマークする

オファーメールを送信したら、Webhook 連携を更新して[資金調達オファーを配信済みとしてマーク](https://docs.stripe.com/api/capital/financing_offers/mark_delivered.md)します。資金調達オファーのステータスが `delivered` であることは、[ダッシュボード](https://dashboard.stripe.com/test/connect/capital)または [Financing Offers API](https://docs.stripe.com/api/capital/financing_offers/retrieve.md) のいずれかで確認できます。

#### curl

```bash
curl https://api.stripe.com/v1/capital/financing_offers/financingoffer_abc123/mark_delivered \
  -u <<YOUR_SECRET_KEY>>:
```

オファーを提供済みとしてマークし、連結アカウントにマーケティングを行ったことを Stripe で確認する必要があります。オファーのメールを送信する際は、BCC [Capital-offers@stripe.com](mailto:capital-offers@stripe.com) に送信してください。

## ステータスの変化をリッスンする [サーバー側]

`capital.financing_offer.created` Webhook に加えて、Stripe は融資オファーがさまざまな状態を遷移する際に追加の Webhook を送信します。Stripe は、すべての Capital Webhook を Connect Webhook エンドポイントではなく、プラットフォームアカウントの Webhook エンドポイントに送信します。Capital に関連する次の Webhook のいずれかを受け取ることができます。

| **Webhook の識別子** | **トリガー** |
| --- | --- |
| `capital.financing_offer.created` | 融資オファーが作成された |
| `capital.financing_offer.accepted` | 連結アカウントがオファーの申し込みを送信する |
| `capital.financing_offer.paid_out` | Stripe がオファーの申し込みを承認し、資金が連結アカウントに入金される |
| `capital.financing_offer.fully_repaid` | 連結アカウントが資金調達残高を完済する |
| `capital.financing_offer.canceled` | 連結アカウントが資金調達オファーをキャンセルする |
| `capital.financing_offer.rejected` | 連結アカウントの申し込みが承認されない |
| `capital.financing_offer.expired` | 融資オファーの期限が切れ、申し込みの対象外になった |
| `capital.financing_offer.replacement_created` | 融資オファーが新しいオファーに[更新された](https://docs.stripe.com/capital/replacements.md) |
| `capital.financing_offer.accepted_other_offer` | 連結アカウントが別の資金調達オファーを承諾する |
| `capital.financing_summary.line_of_credit_update` | 連結アカウントのクレジットラインの条件が更新される |
| `capital.financing_transaction.created` | 資金調達取引が作成される |

[ダッシュボード](https://dashboard.stripe.com/test/connect/capital)で、過去に提供したオファーを探します。

1. オーバーフローメニュー (⋯) をクリックします。
2. **オファーを期限切れにする**オプションをクリックすると、オファーの期限切れをシミュレーションできます。
3. `capital.financing_offer.expired` Webhook が届くことを確認します。

`capital.financing_offer.canceled` を除き、テスト環境ではすべての Webhook をシミュレートできます。

## オファーに申し込む [ダッシュボード] [サーバー側]

オファーへの申し込みを行うと、`capital.financing_offer.accepted` Webhook をシミュレーションすることができます。

1. [ダッシュボード](https://dashboard.stripe.com/test/connect/capital)から、最大融資額が 20,000 USD の配信済みオファーを作成します。
2. `capital_financing_offer` タイプのアカウントリンクを生成し、そのリンクに移動します。ここでは、申し込みが連結アカウントにどのように表示されるかをプレビューできます。
3. 申し込みの最後に到達するまで続け、**送信**をクリックします。
4. `capital.financing_offer.accepted` Webhook が届くことを確認します。
5. ダッシュボードでオファーを表示し、ステータスが受け付け済みであることを確認します。

### 送信後に申請要件に対応

ステータスが `accepted` の資金調達オファーは、申請の審査待ち状態です。審査中、連結アカウントは資金調達レポートページで申請トラッカーを表示し、審査の想定スケジュールを確認して、申請の不備を解消するために必要な対応を行えます。

申請トラッカーを表示するには、次のいずれかを使用します。

- [Capital Financing 組み込みコンポーネント](https://docs.stripe.com/connect/supported-embedded-components/capital-financing.md)
- タイプが `capital_financing_reporting` の [Account Link](https://docs.stripe.com/api/account_links.md)

連結アカウントから申請が送信されると、審査を完了するために、本人確認や銀行口座明細書などの追加情報の提出が要求される場合があります。このような場合、Stripe から連結アカウントに通知メールが直接送信されます。連結アカウントでは、申請トラッカーを通じて要求された情報を送信できます。

追加情報の提出が必要な場合、期限超過の要件が `loans` 機能または `cash_advances` 機能に表示されることがあります。これらの Capital 機能にのみ適用される要件は、`card_payments` や `transfers` など、他のアカウント機能には影響しません。

また、要件が変更されたときには `account.updated` Webhook も送信されます。この Webhook は情報提供を目的としています。アカウントの要件のステータスをすべて反映するものであり、プラットフォームで対応する必要はありません。申請要件に応じて実装を更新するには、`account.updated` Webhook をリッスンし、機能要件 API を使用して、Capital 機能に影響する要件を特定して対応します。詳細については、[機能別の要件の取得](https://docs.stripe.com/connect/handling-api-verification.md?accounts-namespace=v1#retrieve-requirements-by-capability)をご覧ください。

`loans` 機能の要件を取得するリクエストの例は、次のとおりです。

#### curl

```bash
curl https://api.stripe.com/v1/accounts/{{CONNECTED_ACCOUNT_ID}}/capabilities/loans \
  -u <<YOUR_SECRET_KEY>>:
```

レスポンス例は、次のとおりです。

```json
{
  "id": "loans",
  "object": "capability",
  "account": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "currently_due": [
      "{{REQUIREMENT_ID}}.credit_review.form",
      "{{REQUIREMENT_ID}}.identity_verification.challenge"
    ]
  },
  "status": "inactive"
}
```

## 申し込みを承認する [ダッシュボード]

[ダッシュボード](https://dashboard.stripe.com/test/connect/capital)で、受け付けたオファーに対応する行を探します。

1. オーバーフローメニュー (⋯) をクリックします。
2. **承認して資金を支払う**オプションをクリックします。これにより申し込みの承認と資金の入金をシミュレーションできます。
3. 資金が支払われたことを通知する `capital.financing_offer.paid_out` Webhook が届くことを確認します。
4. `capital_financing_reporting` タイプの別の [アカウントリンク](https://docs.stripe.com/api/account_links.md) を生成します。このレポートページでは、連結アカウントの進行中の資金調達について、未払い残高、入金取引、支払い取引の詳細にアクセスできます。
5. **支払いを行う** をクリックし、手動支払いを作成します。

> テスト用融資オファーのレポートページで**支払いを作成**ボタンが有効になるまで、最大で 15 分かかります。

取引の処理後、支払いを取引テーブルで確認します。[financing summary API](https://docs.stripe.com/api/capital/financing_summary.md) を使用すると、進行中の資金調達に対する連結アカウントの返済済み金額をプログラムで表示できます。

#### curl

```bash
curl https://api.stripe.com/v1/capital/financing_summary \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
```

融資のサマリーの取得が正常に行われると、次のようなレスポンスが返されます。

```json
{
  "object": "capital.financing_summary",
  "details": {
    "currency": "usd",
    "advance_amount": 1000000,
    "fee_amount": 100000,
    "withhold_rate": 0.2,
    "remaining_amount": 999950,
    "paid_amount": 50,
    "current_repayment_interval": {
      "due_at": 123456789,
      "remaining_amount": 50,
      "paid_amount": 50
    },
    "repayments_begin_at": 123456789,
    "advance_paid_out_at": 123456789
  }
}
```

## 融資を全額支払う [ダッシュボード]

[ダッシュボード](https://dashboard.stripe.com/test/connect/capital)で、資金を供給した融資に対応する行を探します。

1. オーバーフローメニュー (⋯) をクリックします。
2. **オファーを返済する**オプションをクリックします。これにより、融資残高の完済をシミュレーションできます。
3. 融資が全額支払われたことを通知する `capital.financing_offer.fully_repaid` Webhook が届いていることを確認します。
4. タイプ `capital_financing_reporting` の [Account Link](https://docs.stripe.com/api/account_links.md) を新たに生成します。

連結アカウントが資金調達総額を支払った後は、いつでもレポートページで過去資金調達の詳細にアクセスできます。

## テスト用システムを確認する

ここまでで、お客様の実装は以下のようになっています。

- `capital.financing_offer.created` Webhook を受けて、オファーメールを送信し、オファーを提供済みとしてマークする
- `capital_financing_offer` タイプのアカウントリンクを使用して、プラットフォームダッシュボードに資金調達の申し込みリンクを表示する
- `capital_financing_reporting` タイプのアカウントリンクを使用して、プラットフォームダッシュボードに資金調達レポートのリンクを表示する

プラットフォームダッシュボードの Capital セクションは、連結アカウントの資金調達がどの段階にあるかによって表示が異なる場合があります。考えられる資金調達オファーのステータス値については、以下の状態図を確認してください。

Capital の融資オファーのステートマシン (See full diagram at https://docs.stripe.com/capital/api-integration)

```text
[未提供] --> [配達済み]
[配達済み] --> [承認済み]
[承認済み] --> [入金済み]
[入金済み] --> [完済済み]
[未提供] --> [期限切れ]
[配達済み] --> [期限切れ]
[承認済み] --> [キャンセル済み]
[承認済み] --> [拒否されました]
[入金済み] --> [キャンセル済み]
[未提供] --> [更新済み]
[配達済み] --> [更新済み]
```

| **セグメント** | **プラットフォームにとっての意味** |
| --- | --- |
| 未提供 | Stripe によって資金調達オファーが作成されましたが、承認されたオファー配信チャネルを通じて連結アカウントにはまだ伝達されていません。すべてのオファーはこの状態から開始されます。 |
| 配達済み | 連結アカウントにオファーが送信された、または表示されました。これは配信が行われたことを示すものであり、連結アカウントがオファーを開封、確認、または承諾したことを意味するものではありません。 |
| 承認済み | 連結アカウントがオファーを承諾し、申し込みまたは資金調達プロセスに進みました。必ずしもまだ資金が入金されたわけではなく、必要な審査、承認、または入金がまだ保留中である可能性があります。 |
| 入金済み | 資金調達が連結アカウントに実行されました。これはオリジネーションまたは資金提供のイベントであり、Stripe はプラットフォームのオリジネーション額とレベニューシェアのレポートにこのステータスを使用します。 |
| 完済済み | 連結アカウントは、該当する資金調達手数料を含め、資金調達総額を返済しました。その資金調達の残高はありません。 |

## 自動オファーの有効化に向けて準備する

本番環境で自動オファーを有効にすると、Stripe は連結アカウント向けの資金調達オファーを毎日自動的に作成します。自動オファーを有効にする前に、以下を確認してください。

1. Stripe 共同ブランドのノーコードオファーメールを利用する予定がある場合は、[Comms Center](https://dashboard.stripe.com/connect/comms_center/collect) で連結アカウントのメールアドレスを確認して更新してください。Capital の資金調達を利用するには、返済の進捗状況の更新などの取引関連メールを受信できるよう、連結アカウントで Stripe にメールアドレスを保存しておく必要があります。
2. Financing offers API の本番環境での利用の申請をご希望の場合は、[こちらにお問い合わせください](mailto:capital-review@stripe.com)。

### 追加機能の有効化

時間の経過とともに、一部の連結アカウントが追加融資の対象になる場合があります。追加融資とは、進行中のローンの返済が大幅に進んだ連結アカウントに送信される追加の資金調達オファーです。追加の資金調達オファーに対応するよう実装を更新するには、[追加融資の実装ガイド](https://docs.stripe.com/capital/refills.md)を参照してください。

プラットフォームダッシュボードに Capital 取引を含め、連結アカウントのカスタム入金レポートを更新する場合は、[レポートと照合ガイド](https://docs.stripe.com/capital/reporting-and-reconciliation.md)を参照してください。

## See also

- [追加融資オファー](https://docs.stripe.com/capital/refills.md)
- [オファーを置き換える](https://docs.stripe.com/capital/replacements.md)
- [Capital のテスト](https://docs.stripe.com/capital/testing.md)
- [アカウントリンク](https://docs.stripe.com/api/account_links.md)