コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要
アカウント管理
決済処理
プラットフォーム管理

API によるアカウントの登録時のアカウント確認をテストする

テスト用の API キーを使用した API によるアカウント登録の際に、連結アカウントのさまざまな確認状態をテストする方法の詳細を説明します。

このドキュメントは、API によるアカウント登録、アカウントの更新方法、本人確認について十分に理解していることを前提としています。

確認フローをテストして、アカウントの状態の変化 (支払いを有効または無効にする場合など) に対応できることを確認する必要があります。通常、アカウントの状態は、要件が満たされた後、または処理または時間のしきい値に達したときに変化します。以下のセクションでは、これらの変更と、確認フローをテストする方法について説明します。

初期要件のテスト

まず、サンドボックスで連結アカウントを新規作成し、銀行口座を追加して、アカウント所有者が Stripe 利用規約に同意したことを示します。Stripe では、連結アカウントが Payouts を受け取る前に Stripe 利用規約に明示的に同意することを求めています。この例では、identity.entity_type は company に設定されており、external_account はトークン化された Stripe テストアカウントをリマインダーとして使用して、API コールでの機密情報の漏洩を回避します。

メモ

Connect プラットフォームのユーザー登録を開始した Stripe アカウントからテスト用の API キーを指定する必要があります。自動入力された Stripe のテスト用 API キーを使用すると、これらのサンプルリクエストが失敗します。

Account を作成する際に、identity.country を設定し、card_payments ケイパビリティと stripe_balance.stripe_transfers ケイパビリティをリクエストする必要があります。以下の例は、merchant と recipient の設定を持つプラットフォーム管理アカウントの例です。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "identity": {
        "country": "US",
        "entity_type": "company",
        "attestations": {
            "terms_of_service": {
                "account": {
                    "date": "2019-01-19T19:51:13Z",
                    "ip": "172.18.80.19"
                }
            }
        }
    },
    "dashboard": "none",
    "defaults": {
        "responsibilities": {
            "losses_collector": "application",
            "fees_collector": "stripe"
        },
        "currency": "usd"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        },
        "recipient": {
            "capabilities": {
                "stripe_balance": {
                    "stripe_transfers": {
                        "requested": true
                    }
                }
            }
        }
    }
  }'

この時点でアカウントは作成されますが、確認要件を満たし、入金方法を関連付けるまで、支払いと Payouts は有効になりません。requirements.entries 配列を確認して、取得する必要がある情報を判断します。現在必須のエントリの minimum_deadline.status は currently_due です。

{
  "id": "{% identifier type=\"connectedAccount\" quoteType=\"double\" /%}",
  "object": "account",
  "identity": {
    "country": "US",
    "entity_type": "company"
  },
  "dashboard": "none",
  "defaults": {
    "responsibilities": {
      "losses_collector": "application",
      "fees_collector": "stripe"
    },
    "currency": "usd"
  },
  "configuration": {
    "merchant": {
      "capabilities": {
        "card_payments": {
          "status": "restricted",
          "status_details": [
            {
              "code": "determining_status",
              "resolution": "provide_info"
            }
          ]
        }
      }
    },
    "recipient": {
      "capabilities": {
        "transfers": {
          "status": "restricted",
          "status_details": [
            {
              "code": "determining_status",
              "resolution": "provide_info"
            }
          ]
        }
      }
    }
  },
  "requirements": {
    "summary": {
      "minimum_deadline": { "time": 1700000000, "status": "currently_due" }
    },
    "entries": [
      { "id": "reqent_1", "description": "configuration.merchant.mcc", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_2", "description": "defaults.profile.business_url", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_3", "description": "identity.business_details.address.city", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_4", "description": "identity.business_details.address.line1", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_5", "description": "identity.business_details.address.postal_code", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_6", "description": "identity.business_details.address.state", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_7", "description": "identity.business_details.registered_name", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_8", "description": "identity.business_details.phone", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_9", "description": "identity.business_details.id_numbers.us_ein", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_10", "description": "relationship.representative", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] },
      { "id": "reqent_11", "description": "relationship.owner", "minimum_deadline": { "status": "currently_due" }, "awaiting_action_from": "user", "errors": [] }
    ]
  }
}

次に、レスポンスで特定された必要な情報を取得し、アカウントオブジェクトに追加します。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "defaults": {
        "profile": {
            "business_url": "https://bestcookieco.com"
        }
    },
    "identity": {
        "business_details": {
            "address": {
                "city": "Schenectady",
                "line1": "123 State St",
                "postal_code": "12345",
                "state": "NY"
            },
            "id_numbers": [
                {
                    "type": "us_ein",
                    "value": "000000000"
                }
            ],
            "phone": "8888675309",
            "registered_name": "The Best Cookie Co"
        }
    }
  }'

ビジネスの詳細を更新すると、要件のエントリが変更される場合があります。Person 要件の場合、会社を代表する、または会社を所有する人々の Account オブジェクトの下に Person オブジェクトを作成して更新する必要があります。

Persons API を使用して、アカウントの担当者または代表者の関係を持つ各人物のプロフィールを作成します。この例では、Jenny Rosen のプロフィールを作成し、CEO の肩書きを持つ代表者として指定します。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "relationship": {
        "representative": true,
        "title": "CEO"
    }
  }'

メモ

business_type を individual に設定したアカウントでは、individual プロパティ (individual.first_name など) を 1 つ以上指定すると、Person (人物) オブジェクトが自動的に作成されます。これを行わないか、business_type を company に設定したアカウントでは、アカウントの各 Person を作成する必要があります。

Person を作成すると、レスポンスには requirements.entries ハッシュが含まれ、その人物に必要な本人確認情報がリストされます。

{
  "id": "person_abc",
  "object": "person",
  "requirements": {
    "entries": [
      { "id": "p_req_1", "description": "representative.address.city", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_2", "description": "representative.address.line1", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_3", "description": "representative.address.postal_code", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_3", "description": "representative.address.state", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
``
      { "id": "p_req_4", "description": "representative.date_of_birth.day", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_5", "description": "representative.date_of_birth.month", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_6", "description": "representative.date_of_birth.year", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_7", "description": "representative.phone", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_8", "description": "representative.email", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_9", "description": "identity.attestations.persons_provided.owners", "minimum_deadline": { "status": "currently_due" }, "errors": [] },
      { "id": "p_req_10", "description": "representative.id_numbers. us_ssn_last_4", "minimum_deadline": { "status": "currently_due" }, "errors": [] }
    ]
  }
}

Person を作成し、リクエストされた個人レベルの詳細を指定すると、アカウントの requirements.entries に個人 ID を参照する説明が含まれます。

Jenny Rosen に必要な確認情報を入力するように Person を更新します。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons/
{{PERSON_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "address": {
        "city": "Schenectady",
        "line1": "123 State St",
        "postal_code": "12345",
        "state": "NY"
    },
    "date_of_birth": {
        "day": 10,
        "month": 11,
        "year": 1980
    },
    "id_numbers": [
        {
            "type": "us_ssn_last_4",
            "value": "0000"
        }
    ],
    "phone": "8888675309",
    "email": "jenny@example.com",
    "relationship": {
        "executive": true
    }
  }'

relationship.executive を true に設定すると、代表者が組織に対して重要な支配権を有することが Stripe に対して確認されます。アメリカで必須の確認情報には、アメリカ企業の会社代表者の確認の詳細に関する詳細が記載されています。

所有者を追加するには、別の Person を作成し、その人物をアカウントの owner としてマークします。この例では、Kathleen Banks が The Best Cookie Co. の 80% を所有しています。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "given_name": "Kathleen",
    "surname": "Banks",
    "email": "kathleen@example.com",
    "relationship": {
        "owner": true,
        "percent_ownership": "80"
    }
  }'

会社の 25% 以上の所有権を持つすべての所有者を追加し、identity.attestations.persons_provided.owners を true に設定する必要があります。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v2/core/accounts/
{{CONNECTED_ACCOUNT_ID}}
 \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "identity": {
        "attestations": {
            "persons_provided": {
                "owners": true
            }
        }
    }
  }'

この段階で連結アカウントの初期ユーザー登録が成功すると、以下が可能になります。

  • 必要な情報がすべて入力されました (requirements.summary.minimum_deadline=null)。
  • 支払いはこのアカウントで有効になっています (charges_enabled=true)。
  • Stripe から v2.core.account.updated Webhook イベントを受信しました。

しきい値をテストする

事前ユーザー登録とインクリメンタルアカウント登録のいずれを使用する場合でも、Stripe は、連結アカウントが特定のしきい値に達すると、連結アカウントに関する追加情報をリクエストすることがあります。たとえば、支払いが 1,500 USD に達した後、またはアカウント作成から 30 日後に追加情報が必要になる場合があります。アカウントがしきい値に達した場合に最終的に必要になる可能性がある情報を確認するには、requirements.entries 配列で minimum_deadline.status が eventually_due の要件を確認します。

特定の日付までに必要な情報をご提供いただけない場合、支払いと入金が無効になる可能性があります。これらのシナリオをトリガーしてテストできます。

しきい値のトリガー

確認トークン (tok_visa_triggerVerification) を使用して支払いを作成し、一般的な確認しきい値をトリガーできます。これによって支払いまたは入金がブロックされることはありませんが、追加の情報リクエストはトリガーされます。v2.core.account[requirements].updated Webhook イベントをリッスンしている場合は、以下を確認できます。

  • minimum_deadline.status が currently_due のエントリの requirements.entries
  • requirements.summary.minimum_deadline.time: これらのエントリに適用される最も早い期限を確認する

期日までに必要な情報が提供されない場合のシナリオをテストするには、以下の支払いブロックと入金のセクションを参照してください。

また、本人確認不一致や OFAC しきい値など、より具体的な検証イベントを発生させることもできます。これらのシナリオをテストすると、確認が失敗したときに発生することが多いため便利です。

ブロックされた支払いをテストする

charge block トークン (tok_visa_triggerChargeBlock) を使用してテスト決済を作成することで、支払いをブロックできます。これを行うと、以下を示す v2.core.account[requirements].updated Webhook イベントが届きます。

  • カード支払いの関連するケイパビリティステータスが active ではありません (たとえば、configuration.merchant.capabilities.card_payments.status が active ではい)
  • requirements.entries 配列の必須情報 (minimum_deadline.status および currently_due)
  • まだ必要のないエントリは、minimum_deadline.status と eventually_due として設定されます。

その後、新しい情報でアカウントを更新できます。これにより、別の Webhook イベントがトリガーされます。これは、支払いが有効であり、現在期日または最終的に期日の要件がないことを示します。

ブロックされた入金をテストする

入金をブロックするには、送金ブロックトークン (tok_visa_triggerTransferBlock) を使用してテスト決済を作成します。これを行うと、v2.core.account.updated Webhook イベントが届き、以下が示されます。

  • merchant または recipient の設定の capabilities.stripe_balance.payouts.status が active ではありません
  • minimum_deadline.status が currently_due の requirements.entries 配列で現在必要な情報
  • 最終的に、minimum_deadline.status が eventually_due の requirements.entries 配列に必要な情報

その後、新しい情報を使用してアカウントを更新します。これにより、別の Webhook イベントがトリガーされます。この Webhook は入金が有効になったことと、requirements.summary および requirements.summary.minimum_deadline の両配列が空であることを示します。