トークンを使用してアカウントデータを安全に送信する

連結アカウントの支払いや入金を有効にするには、顧客確認 (KYC) 要件を満たす必要があります。これは、アカウントに関する本人確認情報を Stripe に提供し、その後、Stripe がその情報を確認することで行えます。アカウントトークンと個人トークンを使用することで、このタスクを安全で信頼できる方法で実行できます。トークンにより、個人を特定できる情報 (PII) がサーバーを経由しないため、実装を安全に運用できます。これらのトークンにより、Stripe は不正利用の兆候の検出精度を高めることもできます。

トークンは以下のみに使用できます。

• 法人の詳細 (ビジネスまたは個人に関する情報)
• 個人の詳細
• Stripe Connect アカウント契約への同意を示す

トークンは、以下をはじめとするその他のアカウント情報には「使用できません」。

• アカウントの設定 (入金スケジュールなど)
• アカウントの機密情報以外の情報 (サポート URL、サポート電話番号など)
• 連結アカウントの国

トークンは、Stripe.js、API、またはモバイルクライアントライブラリのいずれかを使用して作成されます。このプロセスは、支払い詳細や外部口座のトークン化と実質的に同じです。連結アカウントの情報は Stripe に直接送信され、トークンと交換されます。このトークンは、create および update の API コールで使用できます。

トークンを作成して使用する

トークンには、クライアント側とサーバ側の両方のコードが必要です。

1. ユーザの入力を取り込む HTML フォームを作成します。
2. Stripe にフォームデータを送信し、その返信としてトークンを受け取り、そのトークンをサーバに送信する JavaScript を追加します。
3. そのトークンをサーバ側の Stripe API コールで使用します。

次の例は、アカウントトークンと個人トークンの使用方法を示しています。企業の法人詳細と個人詳細を提供する際には、両タイプのトークンが必要です。個人のみのアカウントを登録する場合には、個人トークンは必要ありません。その代わりに、アカウントトークンを作成して、Account オブジェクトで individual ハッシュを渡して必要な情報を提供します。

ステップ 1: HTML フォームを作成する

最初のステップは、アカウントと個人の必須情報を収集する HTML フォームを作成することです。これには、Stripe の Connect アカウント契約への同意も含まれます。

アカウント詳細と個人詳細を収集する

フォームエレメントを作成して、名前や住所、およびユーザーの国で必須とされるその他の情報を収集します。

<form class="my-form" action="/create-person" method="post">
  <input type="hidden" name="token-account" id="token-account">
  <input type="hidden" name="token-person" id="token-person">
  <label>
    <span>Business Name</span>
    <input class="inp-company-name">
  </label>
  <fieldset>
    <legend>Business Address</legend>
    <label>
      <span>Street Address Line 1</span>

Stripe の Connect アカウント契約を提示する

プラットフォームは、提供される支払い処理が、Stripe の Connect アカウント契約に従って行われることを、ユーザーに対して明確に提示する必要があります。アカウントトークンを使用して連結アカウントを新規作成する際は、Stripe の Connect アカウント契約への同意が明確に示される必要があります。

Stripe では、以下のような文章を含め、Stripe の利用規約とお客様の利用規約の両方へのリンクを含めることをお勧めします。

<p>By clicking, you agree to <a href="#">our terms</a> and the <a href="https://stripe.com/connect-account/legal">Stripe Connected Account Agreement</a>.</p>

ステップ 2: JavaScript を追加する

次に、ページには以下を実行する JavaScript が必要です。

1. フォーム送信を中断します。
2. stripe.createToken() メソッドを呼び出して、アカウントと個人のトークンを要求する。
3. 受信したトークンの ID をサーバに送信する。

分かりやすくするために、以下のコードではデータ検証とエラー処理を省略していますが、実際の組み込みには両方を追加することを忘れないでください。

stripe.createToken() メソッドに以下の 2 つの引数を指定します。

• 作成するトークンの種類を指定するための値 account または person
• 情報の一般的なオブジェクト

2 番目の引数として提供される JavaScript オブジェクトは、トークン化する Account オブジェクトまたは Person オブジェクトの構造と並列的にする必要があります。Account トークンの最上位には company または individual プロパティが必要であり、Person トークンの最上位には person プロパティが必要です。必要な属性のすべてで、オブジェクトの構造に従います。たとえば、以下のコードブロックの address 内の line1 は、person.address.line1 として指定されます。

ユーザが Stripe の Connect アカウント契約に同意したことを表すには、最上位の tos_shown_and_accepted プロパティに値 true を指定します (これにはアカウントトークンのみが使用されます)。

個人を作成または更新するために、サーバー側のコードを使用して、引き続きトークンを使用する必要があります。アプリケーションから見て効果的なアプローチ (XHR リクエストなど) を使用して、トークン ID をサーバーに送信できます。分かりやすくするために、このコード例では、トークン ID を非表示のフォーム入力に格納してから、フォームを送信します。

// Assumes you've already included Stripe.js!
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const myForm = document.querySelector('.my-form');
myForm.addEventListener('submit', handleForm);

async function handleForm(event) {
  event.preventDefault();

  const accountResult = await stripe.createToken('account', {
    business_type: 'company',
    company: {
      name: document.querySelector('.inp-company-name').value,
      address: {
        line1: document.querySelector('.inp-company-street-address1').value,
        city: document.querySelector('.inp-company-city').value,
        state: document.querySelector('.inp-company-state').value,
        postal_code: document.querySelector('.inp-company-zip').value,
      },
    },
    tos_shown_and_accepted: true,
  });

  const personResult = await stripe.createToken('person', {
    person: {
      first_name: document.querySelector('.inp-person-first-name').value,
      last_name: document.querySelector('.inp-person-last-name').value,
      address: {
        line1: document.querySelector('.inp-person-street-address1').value,
        city: document.querySelector('.inp-person-city').value,
        state: document.querySelector('.inp-person-state').value,
        postal_code: document.querySelector('.inp-person-zip').value,
      },
    },
  });

  if (accountResult.token && personResult.token) {
    document.querySelector('#token-account').value = accountResult.token.id;
    document.querySelector('#token-person').value = personResult.token.id;
    myForm.submit();
  }
}

Stripe からトークンを正常に受け取ると、JavaScript はそのトークン ID を非表示のフォーム入力に格納し、そのフォームを (お客様のサーバに) 送信します。最後のステップでは、サーバ側コードでトークンを使用してアカウントと個人を作成します。

ステップ 3: アカウントを作成する

アカウントトークン ID を使用して、アカウントを作成します。国とビジネスタイプはトークン外で指定されます。

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "controller[stripe_dashboard][type]"=none \
  -d "controller[fees][payer]"=application \
  -d "controller[losses][payments]"=application \
  -d "controller[requirement_collection]"=application \
  -d country=US \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true \
  -d account_token=
{{ACCOUNT_TOKEN_ID}}

アカウントトークンを作成する際に、tos_shown_and_accepted を true に設定すると、Account オブジェクトの tos_acceptance 属性の、date、ip、user_agent 属性が自動的に入力されます。アカウントトークンを使用せずにアカウントを作成した場合は、これらの属性の値を指定する必要があります。

アカウントの個人オブジェクトを作成する際に使用できるようにするため、返されたアカウント ID を必ずメモしておいてください。

ステップ 4: 個人を作成する

個人を作成するには、person_token パラメーターの値として個人トークンの ID を渡します (その個人に対応するアカウント ID も必要です)。Account オブジェクトで requirements ハッシュを使用して、どの個人からどの情報を収集する必要があるかを決定できます。

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d first_name=Jane \
  -d last_name=Diaz \
  -d person_token=
{{PERSON_ID}}

モバイル SDK でアカウントトークンを作成する

Android または iOS の SDK でアカウントトークンを作成することもできます。現在モバイルでは、アカウントトークンのみがサポートされています。これは、個人アカウントの作成には十分ですが、企業アカウントに必要な個人トークンの作成には Stripe.js を使用する必要があります。モバイル SDK での個人トークンのサポートは、今後のリリースで提供される予定です。

import UIKit
import StripePayments

let companyParams = STPConnectAccountCompanyParams()
companyParams.name = company.name
companyParams.address = STPConnectAccountAddress()
companyParams.address.line1 = company.address_line_1
companyParams.address.city = company.address_city
companyParams.address.state = company.address_state
companyParams.address.country = company.address_country
companyParams.address.postalCode = company.address_postal_code

guard let accountParams = STPConnectAccountParams(tosShownAndAccepted: true, company: companyParams) else {
  // The TOS was not accepted
  return
}

STPAPIClient.shared.createToken(withConnectAccount: accountParams) { (accountToken, error) in
    if let error = error {
        // display an error to your user
    }
    else {
        // use account token to create a Connect account server-side
    }
}

ファイルアップロードを処理する

連結アカウントがパスポートなどの本人確認書類を直接撮影したファイルを Stripe に提供する必要がある場合は、アカウントトークンを使用できます。ただし、JavaScript は、ファイルを XHR リクエストの一部として Stripe に送信する必要があるため、より複雑になります。このフローでは、JavaScript によって以下が実行されます。

1. フォーム送信を中断します。
2. ファイルがアップロードされた後に、それを Stripe に送信し、その返信としてファイルトークンを受け取ります。
3. そのファイルトークン ID を、アカウントトークンリクエストの汎用オブジェクトに追加します。
4. stripe.createToken() メソッドを呼び出して、トークンをリクエストします。
5. 受信したアカウントトークンの ID をサーバに送信して、サーバで使用できるようにします。

初めに、フォームにファイルエレメントを追加します。アップロードするファイルは、カラーの画像で (8,000 ピクセル x 8,000 ピクセル未満)、形式は JPG、PNG、PDF のいずれかとして、サイズは 10MB 未満にする必要があります。

<input type="file" id="id-file" name="id-file" accept=".jpeg,.jpg,.png">

次に、フォーム送信を処理する JavaScript で、アップロードされたファイルを Stripe に送信します。これは、アカウントトークンを作成する前に実行する必要があります。

const data = new FormData();
data.append('file', document.querySelector('#id-file').files[0]);
data.append('purpose', 'identity_document');
const fileResult = await fetch('https://uploads.stripe.com/v1/files', {
  method: 'POST',
  headers: {'Authorization': 'Bearer 
pk_test_TYooMQauvdEDq54NiTphI7jx
'},
  body: data,
});
const fileData = await fileResult.json();

最後に、返されたファイル ID を、createToken() コールで指定する汎用オブジェクトに verification.document.front 値として含めます。

const result = await stripe.createToken('account', {
  person: {
    first_name: document.querySelector('.inp-first-name').value,
    last_name: document.querySelector('.inp-last-name').value,
    address: {
      line1: document.querySelector('.inp-street-address1').value,
      city: document.querySelector('.inp-city').value,
      state: document.querySelector('.inp-state').value,
      postal_code: document.querySelector('.inp-zip').value,
    },
    verification: {
        document: {
            front: fileData.id,
            },
        },
    },
  tos_shown_and_accepted: true,
});

法人詳細と個人詳細を更新する

トークンを使用すると、既存のアカウントの法人詳細と個人詳細の情報を安全に更新できます。上記と同じ HTML と JavaScript の組み合わせを使用して必要なトークンを作成し、新しいトークン ID を指定して、Update account (アカウントの更新) コールまたは Update person (個人の更新) コールを実行します。

以前アカウントトークンを通じて設定した法人詳細を更新する際は、新しいトークンを作成して提供する必要があります。

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account_token=
{{ACCOUNT_TOKEN_ID}}

更新にトークンを使用する場合は、次のとおりです。

• 既存の値は新しい値に置き換えられます。
• 新しい値が提供されない場合、既存の値が残ります。
• 既存の値の設定を解除することはできません。
• tos_shown_and_acceptedパラメータは無視され、省略できます。
• アカウントまたは個人の作成時にトークンが最初に使用されたかどうかに関係なく、更新にアカウントまたは個人トークンを使用できます。
• アカウントまたは個人が元々アカウントトークンを使用して作成された場合、別のトークンを使用してのみ値を更新できます。

たとえば、氏名と生年月日のみが格納されたトークンを使用してアカウントを作成する場合は、住所情報のみを含む後続のトークンを作成してから、アカウントの更新コールを実行して、住所の詳細をアカウントに追加します。

法人詳細と個人詳細を削除する

法人情報や個人情報を消去する場合や、値を明示的に null に設定する場合は、update account (アカウントの更新) コールまたは update person (個人の更新) コールで、空白の文字列を渡します。元々トークンを使用していた場合でも、トークンではなく更新コールを使用します。空白の文字列は、オプションの属性にのみ割り当てることができます (住所の 2 行目など)。必須の属性に割り当てることはできません。