Connect OAuth リファレンス

このリファレンスでは、Connect で使用できる OAuth エンドポイントのパブリックメソッドのそれぞれを紹介します。

OAuth Connectフローでは、Stripe に追加のパラメーターを渡すことで、ユーザー体験をカスタマイズできます。一般的ないくつかの例を以下に示します。リファレンスの後半では、その他のすべてのオプションについて記載しています。

注

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

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

拡張プログラムでは、OAuth の動作に変更はありません。Standard プラットフォームの OAuth の変更の詳細をご確認ください。

一般的な例

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

アカウントフォームのフィールドにユーザーのメールアドレスや名前など、既に入手している情報を事前に入力して、新しい Stripe アカウントを作成する必要があるユーザーに可能な限り良好なユーザー体験を提供します。ユーザーに Stripe アカウントがすでにある場合、事前入力は効果がありません。日本での利用規約への同意や RISA への同意など、特定のフィールドは事前に入力できません。

リダイレクト URI を動的に設定する

セキュリティー上の理由から、Stripe はユーザーを事前定義された URI にのみリダイレクトします。ただし、Connect を使用すると、複数のリダイレクト URI を定義できます。これを使用して、ユーザー体験をさらにカスタマイズできます。たとえば、一部のユーザーを https://sub1.example.com に戻し、それ以外のユーザーを https://sub2.example.com にリダイレクトできます。

リダイレクト URI を動的に設定するには、次の手順に従います。

プラットフォーム設定で、リダイレクト URI をそれぞれ追加します。
認証リクエストに redirect_uri パラメータを追加し、その値をリダイレクト URI のいずれか 1 つに設定する。

https://connect.stripe.com/oauth/authorize?response_type=code&client_id={{CLIENT_ID}}&scope=read_write&redirect_uri=https://sub2.example.com

URL に redirect_uri が指定されていない場合、Stripe はプラットフォーム設定で設定された最初の URI を使用します。

アカウントを承認する

Standard アカウントの場合: GET https://connect.stripe.com/oauth/authorize

プラットフォームに連結するためにユーザーを Stripe に送ります。

リクエスト

パラメータ	説明
`client_id`	アプリケーションに付与される一意の ID。アプリケーション設定で確認できます。
`response_type`	現時点で利用できるオプションは、code のみです。
`redirect_uri`オプション	レスポンスのリダイレクトを承認するための URL。これを指定する場合、アプリケーション設定にあるカンマ区切りの `redirect_uri` 値の 1 つと完全に一致する必要があります。ある種の中間者攻撃を防ぐには、本番環境の `redirect_uri` で安全な　HTTPS　接続を使用する必要があります。指定しない場合は、アプリケーション設定の `redirect_uri` がデフォルトになります。
`scope`オプションStandard のみ	read_write または read_only。必要なアクセスのレベルによって異なります。Standard アカウントのデフォルトでは、read_only に設定されています。read_only は拡張機能のみ指定可能であることに注意してください。
`state`オプション	お客様に返される任意の文字列値。CSRF の対策に役立ちます。

次のクエリ文字列パラメーターはすべてオプションです。これらのパラメーターは、新しいユーザー用のアカウントフォームに詳細を事前入力するために使用されます。一部の事前入力済みのフィールド (URL や商品カテゴリーなど) が自動的に非表示に設定されている場合があります。無効な値が指定されたパラメーターは、エラーなどを出力することなく無視されます。

このようなパラメータの一部は、Standard アカウント (以下参照) にのみ適用されます。

パラメータ	説明
`stripe_user[email]`推奨	ユーザのメールアドレス。有効なメール形式で入力してください。
`stripe_user[url]`推奨	ユーザーのビジネスの URL。これは、ユーザーのウェブサイト、アプリケーションのプロフィールページ、ビジネスで公開されている別のプロフィール (LinkedIn や Facebook のプロフィールなど) が該当します。これらは、URL エンコードされ、スキーム (http または https) を含んでいる必要があります。このフィールドの事前入力を有効にする場合は、リンク先のページにユーザーの商品またはサービスの説明と連絡先情報を含めます。十分な情報がない場合、Stripe は入金を開始する前にユーザーに直接連絡を行います。
`stripe_user[country]`	2 文字の国コード (US または CA など)。現時点で、Stripe のサポート対象国である必要があります。
`stripe_user[phone_number]`	ビジネス用の電話番号。10 桁で入力する必要があります。また、`stripe_user[country]` に対応する国を事前入力する必要があります。
`stripe_user[business_name]`	ビジネスの正式名称。
`stripe_user[business_type]`	ビジネスのタイプ。Standard アカウントの場合、値は sole_prop、corporation、non_profit、partnership または llc のいずれかである必要があります。
`stripe_user[first_name]`	Stripe 申請書を記入する人物の名前 (名)。
`stripe_user[last_name]`	Stripe 申請書を記入する人物の名前 (姓)。
`stripe_user[dob_day]` `stripe_user[dob_month]` `stripe_user[dob_year]`	Stripe 申請書を記入する人物の生年月日の年 (YYYY、1900 以降)、月 (1 ～ 12)、日(0 ～ 31)。これらのパラメーターを渡す場合は、3 つすべてを渡す必要があります。
`stripe_user[street_address]`Standard のみ	ビジネスの住所 (番地)。
`stripe_user[city]`Standard のみ	ビジネスの住所 (市)。あいまいにならないように、`stripe_user[country]` に対応する国も事前入力してください。
`stripe_user[state]`Standard のみ	ビジネスの住所 (州)。州を表す 2 文字のコード (アメリカのビジネスの場合は NY、カナダのビジネスの場合は AB など) を指定してください。また、`stripe_user[country]` に対応する国を事前入力する必要もあります。
`stripe_user[zip]`Standard のみ	ビジネスの住所 (郵便番号)。文字列で指定してください。あいまいにならないように、`stripe_user[country]` に対応する国も事前入力してください。
`stripe_user[physical_product]`Standard のみ	文字列: ユーザが物品を販売している場合は true、それ以外の場合は false です。
`stripe_user[product_description]`	ビジネスが支払いを受け付けている対象についての説明。
`stripe_user[currency]`Standard のみ	通貨を表す小文字の 3 文字の ISO コード (usd または cad など)。Stripe がサポートする有効な国と通貨の組み合わせである必要があります。`stripe_user[country]` に対応する国を事前入力する必要があります。
`stripe_user[first_name_kana]`	Stripe 申請書を記入する人物の名前 (名) のカナ表記。このパラメーターは日本のみを対象としているため、`stripe_user[country]` に JP を事前入力する必要があります。
`stripe_user[first_name_kanji]`	Stripe 申請書を記入する人物の名前 (名) の漢字表記。このパラメーターは日本のみを対象としているため、`stripe_user[country]` に JP を事前入力する必要があります。
`stripe_user[last_name_kana]`	Stripe 申請書を記入する人物の名前 (姓) のカナ表記。このパラメーターは日本のみを対象としているため、`stripe_user[country]` に JP を事前入力する必要があります。
`stripe_user[last_name_kanji]`	Stripe 申請書を記入する人物の名前 (姓) の漢字表記。このパラメーターは日本のみを対象としているため、`stripe_user[country]` に JP を事前入力する必要があります。
`stripe_user[gender]`	Stripe 申請書を記入する人物の性別 (国際規制に基づき、男性または女性のいずれかにする必要があります)。このパラメーターは日本のみを対象としているため、`stripe_user[country]` に JP を事前入力する必要があります。
`stripe_user[block_kana]`Standard のみ	住所ブロックのカナ表記。このパラメータは日本のみを対象としています。このパラメータを使用するには、`stripe_user[country]` に JP、`stripe_user[zip]` に日本の有効な郵便番号を事前入力する必要があります。
`stripe_user[block_kanji]`Standard のみ	住所ブロックの漢字表記。このパラメータは日本のみを対象としています。このパラメータを使用するには、`stripe_user[country]` に JP、`stripe_user[zip]` に日本の有効な郵便番号を事前入力する必要があります。
`stripe_user[building_kana]`Standard のみ	住所 (建物) のカナ表記。このパラメータは日本のみを対象としています。このパラメータを使用するには、`stripe_user[country]` に JP、`stripe_user[zip]` に日本の有効な郵便番号を事前入力する必要があります。
`stripe_user[building_kanji]`Standard のみ	住所 (建物) の漢字表記。このパラメータは日本のみを対象としています。このパラメータを使用するには、`stripe_user[country]` に JP、`stripe_user[zip]` に日本の有効な郵便番号を事前入力する必要があります。

レスポンス

ユーザーのブラウザーは、設定したリダイレクト URI または redirect_uri パラメーターで渡した値にリダイレクトされます。成功すると、次のクエリパラメーターが返されます。

パラメータ	説明
`code`	ユーザのアクセストークンを取得するために、次の呼び出しで使用可能な認証コード。1 回のみ使用でき、5 分後に有効期限が切れます。
`scope`	read_write または read_only。最初の GET リクエストで渡した値によって決まります。
`state`	最初の GET リクエストで指定した `state` パラメータの値。

エラーレスポンス

エラーが発生した場合は、access_denied の場合を除き、ユーザーのブラウザーはリダイレクトされません。以下のフィールドを含む JSON ディクショナリーでエラーが返されます。

パラメータ	説明
`error`	エラータイプごとの一意のエラーコード。
`error_description`	人間が理解できるエラーの説明。
`state`	最初の GET リクエストで指定した `state` パラメータの値。

エラーコード

パラメータ	説明
`access_denied`	ユーザが認証を拒否しました。
`invalid_scope`	無効な `scope` パラメータが指定されています。
`invalid_redirect_uri`	指定された `redirect_uri` パラメーターが無効な URL であるか、アプリケーション設定で許可されていません。
`invalid_request`	`response_type` パラメータがありません。
`unsupported_response_type`	サポートされていない `response_type` パラメータ。現在サポートされている `response_type` は code のみです。

連結を完了し、アカウント ID を取得する

POST https://connect.stripe.com/oauth/token

authorization_code をアカウントの連結に変換するためと、refresh_token を使用して新しいアクセストークンを取得するための両方に使用されます。

リクエスト

シークレット API キーを client_secret POST パラメータとして使用して、このコールを行います。

認証コードをアクセストークンに変換する際は、認証コードの環境 (本番またはテスト) に対応する API キーを使用する必要があります (使用した client_id が本番用か開発用かによって決まります)。

更新トークンを使用してアクセストークンをリクエストする場合は、テスト用または本番用の API キーを使用して、それぞれテスト用 / 本番用のアクセストークンを取得できます。同じスコープと環境 (本番またはテスト) が設定されている既存のアクセストークンは取り消されます。

注

OAuth v2 によると、このエンドポイントはべき等ではありません。認証コードを複数回使用すると、アカウントの連結が取り消されます。

パラメータ	説明
`grant_type`	認証コードをアクセストークンに変換する際は authorization_code、更新トークンを使用して新しいアクセストークンを取得する際は refresh_token。
`code` または `refresh_token`	`code` または `refresh_token` の値。`grant_type` によって決まります。
`scope`オプション	更新トークンから新しいアクセストークンをリクエストする場合、更新トークンと同等またはそれ以内の任意の対象範囲。認証コードからアクセストークンをリクエストした場合は作用しません。デフォルトでは、更新トークンの対象範囲に設定されています。

レスポンス

パラメータ	説明
`scope`	アクセストークンで権限が付与される対象範囲。認証コードと `scope` パラメータの対象範囲によって決まります。
`stripe_user_id`	アクセスを許可しているアカウントの一意の ID (文字列)。
`livemode`	連結アカウントの代わりに更新を行うプラットフォームのアクセスが、本番環境アクセスを含むか、テスト環境でのアクションに限定されるかを示すものです。これは、OAuth リクエストの認証に使用されるアプリケーションの本番環境と一致します。
`token_type`	常に、値 bearer が設定されます。
`access_token`	非推奨 `Stripe-Account` のヘッダーを、この Stripe アカウントの代理としてリクエストを実行できるプラットフォームのシークレットキーを指定して使用します。
`stripe_publishable_key`	非推奨 `Stripe-Account` のヘッダーを、この Stripe アカウントの代理としてリクエストを実行できるプラットフォームの公開可能キーを指定して使用します。
`refresh_token`	非推奨対象範囲が同等か狭い、または別の本番環境の新しいアクセストークンを取得するために使用できます (適用可能な場合)。

エラーレスポンス

パラメータ	説明
`error`	エラータイプごとの一意のエラーコード。
`error_description`	人間が理解できるエラーの説明。

エラーコード

パラメータ	説明
`invalid_request`	`code`、`refresh_token`、または `grant_type` パラメータが指定されていません (必須の場合)。
`invalid_grant`	以下のように、さまざまなことがこのエラーを引き起こす可能性があります。 `code` が存在しないか、期限切れであるか、使用されているか、お客様のものではない場合 `refresh_token` が存在しないか、お客様のものではない場合 API キーの環境 (本番キーまたはテストキー) が `code` または `refresh_token` の環境と一致しない
`unsupported_grant_type`	指定された `grant_type` パラメータがサポートされていません。現在サポートされているタイプは、authorization_code および refresh_token のみです。
`invalid_scope`	無効な `scope` パラメータが指定されています。
`unsupported_response_type`	サポートされていない `response_type` パラメータ。現在サポートされている `response_type` は code のみです。

アカウントのアクセスを取り消す

POST https://connect.stripe.com/oauth/deauthorize

アカウントへのアクセスを取り消すために使用されます。

注

Standard アカウントのプラットフォームへのアクセスのみを取り消すことができます。

リクエスト

シークレット API キーを Authorization ヘッダとして使用してこのコールを行います。

アカウントのアクセス権を取り消す場合は、アカウントの接続に使用された環境 (本番またはテスト) に対応する API キーを使用する必要があります。本番環境の client_id が接続を作成した場合は、本番 API キーを使用し、開発環境の client_id が接続を作成した場合は、テスト API キーを使用します。

パラメータ	説明
`client_id`	アカウントの連結を解除するアプリケーションの `client_id`。アカウントはこのアプリケーションに連結されている必要があります。
`stripe_user_id`	連結解除するアカウント。

レスポンス

パラメータ	説明
`stripe_user_id`	アクセスを取り消したアカウントの一意の ID (文字列)。前に渡した `stripe_user_id` と同一です。これが返された場合は、アクセス権の取り消しが成功しています。

エラーレスポンス

パラメータ	説明
`error`	エラータイプ別の一意のエラーコード。
`error_description`	人間が理解できるエラーの説明。

エラーコード

パラメータ説明

invalid_request client_id または stripe_user_id パラメータが指定されていません (必須の場合)。

パラメータ	説明
`invalid_request`	`client_id` または `stripe_user_id` パラメータが指定されていません (必須の場合)。
`invalid_client`	以下のように、さまざまなことがこのエラーを引き起こす可能性があります。 `client_id` がお客様のものではない場合 `stripe_user_id` が存在しないか、お客様のアプリケーションと連結されていない場合 API キーの環境 (本番キーまたはテストキー) が `client_id` の環境と一致しない `no_deauth_on_controlled_account`: アカウントの連結解除ができない場合は、代わりに Rejection API を使用します。

invalid_client

以下のように、さまざまなことがこのエラーを引き起こす可能性があります。

client_id がお客様のものではない場合
stripe_user_id が存在しないか、お客様のアプリケーションと連結されていない場合
API キーの環境 (本番キーまたはテストキー) が client_id の環境と一致しない
no_deauth_on_controlled_account: アカウントの連結解除ができない場合は、代わりに Rejection API を使用します。