Express アカウントで OAuth を使用する非推奨

OAuth 連結フロー

ユーザは次の OAuth 連結フローを使用してプラットフォームに連結します。

1. 自社サイトのページで、ユーザーを Stripe にリダイレクトするリンクを提供し、プラットフォームの client_id を渡します。
2. Stripe の Web サイトで、ユーザはプラットフォームに連結するための必須情報を入力します。
3. Stripe は、認証コードとともにユーザーをお客様のサイトにリダイレクトします。
4. サイトから Stripe の OAuth トークンのエンドポイントに対して、連結を完了してユーザのアカウント ID をフェッチするようリクエストが行われます。

上記のステップが完了すると、ユーザのアカウント ID を使用して API リクエストを実行できるようになります。

ステップ 1: OAuth リンクを提供する

組み込みを開始するには、プラットフォームの設定に移動して以下の操作を行います。

• OAuth 設定で、OAuth を使用する Express アカウントのアカウント登録を有効にします。
• client_id(Stripe によって生成されるプラットフォームの一意の ID) をコピーします。
• redirect_uri を設定します。これは、ユーザがアカウントの連結後にリダイレクトされる URL です。プラットフォームの設定で、すべてのリダイレクト URL を指定する必要があります。リクエストに redirect_uri パラメータを含めなかった場合、プラットフォームの設定で最初に設定したアドレスがデフォルトとして使用されます。

Stripe は、テストを実行しやすくするための開発用 client_id も提供しています。

これら 2 つの情報を用意したら、OAuth リンクを作成できます。ユーザを Stripe の Express OAuth エンドポイントに送るための連結ボタンを表示することをお勧めします。

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://connect.stripe.com/connect/default/oauth/test&client_id=ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb&state={STATE_VALUE}

CSRF 攻撃を防止するには、値を一意のトークンに設定した state パラメーターを追加します。Stripe はこの state 値を、ユーザーをお客様のサイトに戻すリダイレクト URL に含めます。その後、この state パラメーターが、最初に提供した値と同じであることを確認します。

Stripe との連結 ボタンとサンプル URL は以下のように表示されます。

OAuth パラメータを使用して Express をカスタマイズする

Express アカウント登録フローの動作を変更するには、追加の URL パラメータを OAuth リンクに加えます。使用できるパラメータの一覧については、OAuth リファレンスを参照してください。

個人または会社のアカウント

stripe_user[business_type] パラメーターを、individual または company に設定することにより、個人用と会社用のどちらの Express アカウント登録フォームを表示するかを指定できます。

Stripe は、各アカウントタイプに対応する適切な情報を収集します。たとえば、会社のアカウント登録は以下のようになります。

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://connect.stripe.com/connect/default/oauth/test&client_id=ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb&state={STATE_VALUE}&stripe_user[business_type]=company

フォームフィールドを事前入力する

ユーザの Stripe 申請書の一部のフォームフィールドを事前入力するには、関連する URL パラメータを OAuth リンクに含めます。

この例では、stripe_user[email] を使用してユーザのメールアドレスを事前入力しています。

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://connect.stripe.com/connect/default/oauth/test&client_id=https://connect.stripe.com/connect/default/oauth/test&state={STATE_VALUE}&stripe_user[email]=user@example.com

アカウントのケイパビリティを指定する

Express に関するダッシュボードの設定で、新規の連結アカウントに適用されるケイバビリティを変更できます。ただし、連結アカウントごとに異なるケイパビリティをリクエストする場合は、OAuth リンクに suggested_capabilities[] パラメーターを含め、Express の設定ページでダッシュボードの設定を上書きできます。

transfers ケイパビリティを使用した例:

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://connect.stripe.com/connect/default/oauth/test&client_id=ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb&state={STATE_VALUE}&suggested_capabilities[]=transfers

Stripe は、以下のいずれかの条件に一致しない限り、提示されたケイパビリティをこの Express アカウントに追加します。

• ユーザが transfers に対応していない国にいる場合、Stripe はそのアカウントを card_payments として指定します。
• ユーザーのアカウントが transfers と card_payments の「どちら」にも対応していない場合、そのアカウントはケイパビリティなしとしてマークされます。

assert_capabilities[] パラメータを使用して、提示されたケイパビリティを Stripe が追加したかどうかを確認できます。このステップはオプションです。

ステップ 2: ユーザーがアカウントを作成する

ユーザーがお客様のサイトのリンクをクリックすると、Stripe の Web サイトが表示され、そこで連絡先と入金情報を入力するように求められます。

アカウント登録プロセスをテストするには、電話番号として「(000) 000-0000」を入力します。Stripe から SMS メッセージまたはメールは送信されませんが、「000-000」のコードで確認を完了できます。

Express では、アカウント登録フローと Express ダッシュボードでお客様のブランディングを表示します。プラットフォーム名、ロゴ、オプションのブランドカラーを、Stripe ダッシュボードの Connect の設定セクションで指定できます。

ステップ 3: Stripe がユーザーをお客様のサイトにリダイレクトする

ユーザーがアカウント登録プロセスを完了すると、Stripe はプラットフォームの redirect_uri として定義された URL を使用して、ユーザーをお客様のサイトに戻します。

連結が成功すると、リダイレクト URL に次の値が含まれます。

• state 値 (指定されている場合)。
• 認証コード。認証コードは一時的なコードであり、次のステップで説明する POST リクエスト内で 1 回のみ使用できます。

https://connect.stripe.com/connect/default/oauth/test?code={AUTHORIZATION_CODE}

ステップ 4: お客様が Express アカウントの連結を完了する

提供された認証 code を Stripe のトークンエンドポイントへの POST リクエストに含めて、連結を完了しユーザのアカウント ID をフェッチします。

curl https://connect.stripe.com/oauth/token \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "code"="ac_123456789" \
  -d "grant_type"="authorization_code"

Stripe はユーザのアカウント ID (stripe_user_id) を含むレスポンスを返します。

{
  "livemode": false,
  "token_type": "bearer",
  "stripe_user_id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "scope": "express",
  ...
}

問題が発生した場合は、Stripe から詳細なエラーメッセージが返されます。

{
  "error": "invalid_grant",
  "error_description": "Authorization code does not exist: {AUTHORIZATION_CODE}"
}

これで、ユーザはプラットフォームに連結されました。stripe_user_id は新しいアカウントの Stripe アカウント ID です。この値をデータベースに保存するとともに、Stripe-Account ヘッダでリクエストに渡して、連結アカウントとしての認証に使用します。

アカウントのケイパビリティを確認する

suggested_capabilities[] パラメーターを指定する場合、assert_capabilities[] パラメーターを追加して、提示されたケイパビリティが連結アカウントに適用されたかどうかを確認できます。たとえば、URL のセキュリティーに懸念がある場合にはこの確認をお勧めします。ただし、このステップはオプションです。Stripe はケイパビリティの適用エラーに自動的に対処します。

curl https://connect.stripe.com/oauth/token \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "code"="ac_123456789" \
  -d "grant_type"="authorization_code" \
  -d "assert_capabilities[]"="transfers"

成功のレスポンスは次のようになります。

{
  "livemode": false,
  "token_type": "bearer",
  "stripe_user_id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "scope": "express",
  "capabilities": "transfers",
  ...
}

指定された capabilities[] 値が一致しない場合は、以下のようなエラーが返されます。

{
  "error": "invalid_request",
  "error_description": "assert_capabilities expects capability: card_payments"
}

このリクエストが失敗する最も一般的な理由は、指定されたケイパビリティーがユーザーの国で使用できないためです。また、可能性としては低いですが、悪意のある第三者が URL を変更していることも考えられます。

Webhook

アカウントが作成されると、そのアカウントの変更に関する通知はすべて、account.updated イベントとして Webhook に送信されます。アカウントの設定で Connect Webhook URL を設定します。これらのイベントによって、連結アカウントのアカウント登録と確認ステータスを追跡できます。これは、ユーザーサポートを提供したり、プラットフォームのユーザーインターフェイスに関連する通知を表示する際に使用できます。また、別の方法として、ユーザーへのアカウント登録手順や確認プロセスの説明、問題が生じた場合の対応を Stripe に任せることもできます。

テスト API キーまたは client_id を使用してサンドボックスでアカウントを作成した場合、お客様のシステムの構築中に Stripe からメールを送信することはありません (ただし、本番環境では送信されます)。