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

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

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

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

初期要件のテスト

まず、サンドボックスで新しい連結アカウントを作成し、銀行口座を追加して、アカウント所有者が Stripe 利用規約に同意したことを確認します。Stripe では、連結アカウントは入金を行う前に Stripe の利用契約に明示的に同意する必要があります。この例ではより複雑なシナリオを説明するため、business_type を company に設定し、external_account にはトークン化された Stripe のテストアカウントを指定して、万が一にも API コールで機密情報が公開されないようにしています。

注

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

連結アカウントはコントローラープロパティを使用するか、アカウントタイプを設定して作成できます。いずれの場合も、国を設定して、card_payments ケイパビリティと transfers ケイパビリティをリクエストする必要があります。

この時点でアカウントが作成されますが、支払いと入金はまだ無効になっています。レスポンスで、requirements.currently_due 配列を確認して、収集する必要がある情報を特定します。

{
  "id": "{{CONNECTED_ACCOUNT_ID}}"
,
  "object": "account",
  "requirements": {
    "currently_due": [
      "business_profile.mcc",
      "business_profile.url",
      "company.address.city",
      "company.address.line1",
      "company.address.postal_code",
      "company.address.state",
      "company.name",
      "company.phone",
      "company.tax_id",
      "relationship.representative",
      "relationship.owner"
    ],
    ...
  },
  ...
}

次に、レスポンスで返された外部アカウントの id を使用し、アカウントに関する必要な追加情報を提供してアカウントを更新します。

会社の詳細が正しく更新された後で、requirements.currently_due を確認すると、relationship 要件がまだ必要であることが示されます。

{
  "id": "{{CONNECTED_ACCOUNT_ID}}"
,
  "object": "account",
  "requirements": {
    "currently_due": [
      "relationship.representative",
      "relationship.owner",
    ],
    ...
  },
  ...
}

Persons API を使用して、アカウントとの関係を表す個人のプロフィールを作成します。この例では、Jenny Rosen のプロフィールを作成し、representative と指定します。さらに、この例ではオプションの title 属性も入力しています。

注

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

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

{
  "id": "{{CONNECTED_ACCOUNT_ID}}"
,
  "object": "account",
  "requirements": {
    "currently_due": [
      "address.city",
      "address.line1",
      "address.postal_code",
      "address.state",
      "dob.day",
      "dob.month",
      "dob.year",
      "phone",
      "email",
      "relationship.executive",
      "ssn_last_4"
    ],
    ...
  },
  ...
}

外部アカウントの Person を作成した後で Account オブジェクトをチェックすると、新たに作成された Person に必要な本人確認情報が requirements.currently_due リストに追加されていることを確認できます。

{
  "id": "{{CONNECTED_ACCOUNT_ID}}"
,
  "object": "account",
  "requirements": {
    "currently_due": [
      "person.person_xxx.address.city",
      "person.person_xxx.address.line1",
      "person.person_xxx.address.postal_code",
      "person.person_xxx.address.state",
      "person.person_xxx.dob.day",
      "person.person_xxx.dob.month",
      "person.person_xxx.dob.year",
      "person.person_xxx.phone",
      "person.person_xxx.email",
      "person.person_xxx.relationship.executive",
      "person.person_xxx.ssn_last_4",
      "relationship.owner"
    ],
    ...
  },
  ...
}

Update a Person API を使用して、Jenny Rosen に必要な本人確認情報を提供します。

relationship[executive]=true を設定して、代表者が組織内で重要な支配権を持っている人物であることを Stripe に対して宣言します。アメリカの企業の会社代表者の本人確認については、アメリカで必須の本人確認情報で詳細をご覧ください。

representative 情報を提供した後で、Stripe ではさらにアカウントの owner を識別する必要があります。この例では、Kathleen Banks が The Best Cookie Co. の 80% を所有しています。

例では、Kathleen Banks が所有しているのは The Best Cookie Co. の 100% 未満です。所有権の合計を 100% にする別の所有者が定義されていないため、Stripe はお客様に対して必要なすべての所有者に関する情報を収集したことを確認するように求めます。

この段階で連結アカウントの処理が正常に完了することは、次を意味します。

必要な情報の収集をすべて完了しました (requirements.currently_due=null)。
支払いはこのアカウントで有効になっています (charges_enabled=true)。
Stripe から account.updated Webhook を受信しました。

しきい値をテストする

アップフロントアカウント登録またはインクリメンタルアカウント登録のどちらを使用している場合も、さまざまなしきい値に達したときに、連結アカウントに関する詳細情報の提出を、Stripe からリクエストすることがあります。これらのしきい値は、確認の失敗または OFAC チェックによってトリガーされる場合があります。また、processing または time コンポーネントによってトリガーされることもあります。たとえば、支払いが 1,500 USD に達した後、またはアカウントの作成から 30 日後 (いずれか早い方) に詳細情報の提出を求められる場合があります。必要な情報と期日を確認するには、requirements.eventually_due 配列と requirements.current_deadline タイムスタンプをチェックします。

特定の期日までに新しい情報が収集されていない場合は、情報が収集されるまで、支払いと入金が無効になることがあります。これらのシナリオをトリガーしてしきい値をテストし、必要な情報を収集できます。

しきい値のトリガー

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

requirements.currently_due をチェックして、収集が必要な情報を判断します。
requirements.current_deadline をチェックして、情報が必要になる期日を確認します。

情報が current_deadline までに収集されない場合、支払いと入金が無効になることがあります。このようなシナリオをテストするには、以下の支払いのブロックと入金のブロックのセクションをご覧ください。

ID の不一致がある場合や OFAC しきい値に達した場合など、より詳細な確認しきい値をトリガーできます。これらは確認が失敗したときに発生することが多いため、これらのしきい値をテストすることが役立ちます。

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

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

charges_enabled=false
requirements.currently_due 配列内の必須の情報。
空の requirements.eventually_due 配列。

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

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

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

payouts_enabled=false
requirements.currently_due 配列内の必須の情報。
空の requirements.eventually_due 配列。

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