プラットフォームが管理する Standard アカウントで OAuth を使用する

OAuth 連結フローを使用して Stripe ユーザーがプラットフォームに連結できるようにします。

新しい Connect プラットフォームへの OAuth の使用は推奨されていません。代わりに、Standard アカウントでの Connect アカウント登録を行うことをお勧めします。

2021 年 6 月から、read_write の範囲で OAuth を使用しているプラットフォームは、別のプラットフォームで管理されている Standard アカウントに接続できなくなります。

拡張プログラムでは、OAuth の動作に変更はありません。プラットフォームが管理する Standard アカウント向けの OAuth の変更の詳細をご確認ください。

OAuth 連結フロー

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

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

注

プラットフォームでは、アカウント向けに作成したデータ (請求金額、顧客、請求書など) が、顧客の Stripe アカウントに表示される点に注意してください。これにより、そのユーザーが他のプラットフォームに連結した場合、それらのプラットフォームにもそのデータが表示されるようになります。

OAuth リンクを作成する

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

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

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

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

https://connect.stripe.com/oauth/authorize?response_type=code&client_id=ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb&scope=read_write

Stripe エンドポイントは、少なくとも次の 3 つのパラメータを受け入れる必要があります。

code の値を含む response_type
client_id
read_write の値を含む scope

scope パラメータは、連結アカウントの代理としてプラットフォームが実行できることを指定します。デフォルトは read_only に設定されています。

CSRF 攻撃を防止するには、値として一意のトークンを渡して、state パラメーターを追加します。ユーザーをお客様のサイトにリダイレクトする際に指定した state を含めます。サイトでは、state パラメーターが変更されていないことを確認する必要があります。

Connect with Stripe (Stripe に連結) ボタンとともに、上記の URL をユーザに提示して連結を開始する方法です。

連結する

OAuth パラメーターを使用してアカウント登録をカスタマイズする

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

ユーザがアカウントを作成または連結する

ユーザがお客様のサイトのリンクをクリックすると、Stripe の Web サイトに移動し、プラットフォームへの連結を許可または拒否するように求められます。

Stripe アカウントを作成するプロセスは、認証フローに組み込まれています。ユーザがすでにアカウントを持っているかどうかを心配する必要はありません。

ユーザはログインしており、プラットフォームに直接連結するためのアカウントを選択できます。

ユーザはアカウントを作成する必要があります。

ユーザがお客様のサイトにリダイレクトされる

ユーザの既存または新規作成したアカウントをプラットフォームに連結すると、顧客は再度お客様のサイトの、プラットフォームの redirect_uri として規定された URL にリダイレクトされます。

連結に成功すると、次の値が URL に渡されます。

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

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

ユーザが認証を拒否した場合でも、お客様のサイトにリダイレクトされますが、URL には認証コードではなくエラーが含まれます。

https://connect.stripe.com/connect/default/oauth/test?error=access_denied&error_description=The%20user%20denied%20your%20request

プラットフォームがアカウントの連結を完了する

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

本番環境またはテスト環境のアクセストークンのどちらを取得するかに応じて、本番環境またはテスト環境の API シークレットキーでリクエストを作成します。

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

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

問題が発生した場合は、代わりにエラーが返されます。

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

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

アプリケーションでは、専用の OAuth クライアントライブラリを使用してこれらの手順の簡素化を検討することをお勧めします。ご使用の言語またはフレームワークの OAuth ライブラリを確認するには、OAuth Web サイトのクライアントライブラリのリストをご覧ください。

refresh_token は、本番環境での client_id のテスト用アクセストークンの生成や、アクセストークンのロールに使用できます。最初の POST リクエストの後でしか取得できないため、この値も保持する必要があります。

注

受け取ったアカウント ID は保存してください。 プラットフォームがユーザの代わりにリクエストを実行するには、この情報が必要です。

取り消し後または取り消し中のアクセス

ユーザがアカウントからお客様のプラットフォームの連結を解除すると、account.application.deauthorized イベントが発生します。Webhook でこのイベントを確認することにより、サーバで必要なクリーンアップを実行できます。

プラットフォームから Stripe ダッシュボードにアクセスできるアカウントの連結を解除するには、お客様の client_id と、連結アカウントの ID を connect.stripe.com/oauth/deauthorize に POST します。

ユーザーの代わりに API を使用して、決済の受け付け、継続請求の設定、アカウントデータの取得などを実行できます。