# Connect OAuth リファレンス

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

OAuth *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients)フローでは、Stripe に追加のパラメーターを渡すことで、ユーザー体験をカスタマイズできます。一般的ないくつかの例を以下に示します。リファレンスの後半では、その他のすべてのオプションについて記載しています。

> プラットフォームでは、Standard アカウント向けに作成したデータ (請求金額、顧客、*請求書* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice)など) が、Stripe アカウントに表示される点に注意してください。これにより、そのユーザーが他のプラットフォームに連結した場合、それらのプラットフォームにもそのデータが表示されるようになります。
> 
> 2021 年 6 月から、`read_write` の範囲で OAuth を使用しているプラットフォームは、別のプラットフォームで管理されているアカウントに接続できなくなります。
> 
> [拡張プログラム](https://docs.stripe.com/building-extensions.md)では、OAuth の動作に変更はありません。[Standard プラットフォームの OAuth の変更](https://docs.stripe.com/connect/oauth-changes-for-standard-platforms.md)の詳細をご確認ください。

## 一般的な例

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

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

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

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

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

1. [プラットフォーム設定](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth)で、リダイレクト URI をそれぞれ追加します。
2. 認証リクエストに `redirect_uri` パラメータを追加し、その値をリダイレクト URI のいずれか 1 つに設定する。

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

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

## アカウントを承認する

`GET https://connect.stripe.com/oauth/authorize`

ユーザーがプラットフォームに接続できるよう、Stripe にリダイレクトします。

### リクエスト

| パラメータ | 説明 |
| --- | --- |
| `client_id` | アプリケーションに付与される一意の ID。[アプリケーション設定](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth)で確認できます。 |
| `response_type` | 現時点で利用できるオプションは、**code** のみです。 |
| `redirect_uri`(オプション) | [レスポンス](https://docs.stripe.com/connect/oauth-reference.md#get-authorize-response)のリダイレクトを承認するための URL。これを指定する場合、[アプリケーション設定](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth)にあるカンマ区切りの `redirect_uri` 値の 1 つと完全に一致する必要があります。ある種の中間者攻撃を防ぐには、本番環境の `redirect_uri` で安全な　HTTPS　接続を使用する必要があります。指定しない場合は、アプリケーション設定の `redirect_uri` がデフォルトになります。 |
| `scope`(オプション) | 必要なアクセスレベルに応じて、**read\_write** または **read\_only** を指定します。デフォルトは **read\_only** です。注: **read\_only** は[拡張機能に対してのみ指定できます](https://docs.stripe.com/connect/oauth-changes-for-standard-platforms.md)。 |
| `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]` | 事業形態。値は **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 コード](https://en.wikipedia.org/wiki/ISO_4217) (**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](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth) または `redirect_uri` パラメーターで渡した値にリダイレクトされます。成功すると、次のクエリパラメーターが返されます。

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

### エラーレスポンス

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

| パラメータ | 説明 |
| --- | --- |
| `error` | エラータイプごとの一意の[エラーコード](https://docs.stripe.com/connect/oauth-reference.md#get-authorize-error-codes)。 |
| `error_description` | 人間が理解できるエラーの説明。 |
| `state` | 最初の GET リクエストで指定した `state` パラメータの値。 |

### エラーコード

| パラメータ | 説明 |
| --- | --- |
| `access_denied` | ユーザが認証を拒否しました。 |
| `invalid_scope` | 無効な `scope` パラメータが指定されています。 |
| `invalid_redirect_uri` | 指定された `redirect_uri` パラメーターが無効な URL であるか、[アプリケーション設定](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth)で許可されていません。 |
| `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 パラメータとして使用して、このコールを行います。

#### curl

```bash
curl https://connect.stripe.com/oauth/token \
  -u <<YOUR_SECRET_KEY>>: \
  -d "code"="ac_123456789" \
  -d "grant_type"="authorization_code"
```

認証コードをアクセストークンに変換する際は、認証コードの環境 (本番またはテスト) に対応する 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 リクエストの認証](https://docs.stripe.com/connect/oauth-reference.md#get-authorize)に使用されるアプリケーションの本番環境と一致します。 |
| `token_type` | 常に、値 **bearer** が設定されます。 |
| `access_token` | (非推奨) `Stripe-Account` の[ヘッダー](https://docs.stripe.com/connect/authentication.md#stripe-account-header)を、この Stripe アカウントの代理としてリクエストを実行できるプラットフォームのシークレットキーを指定して使用します。 |
| `stripe_publishable_key` | (非推奨) `Stripe-Account` の[ヘッダー](https://docs.stripe.com/connect/authentication.md#stripe-account-header)を、この Stripe アカウントの代理としてリクエストを実行できるプラットフォームの公開可能キーを指定して使用します。 |
| `refresh_token` | (非推奨) 対象範囲が同等か狭い、または別の本番環境の新しいアクセストークンを取得するために使用できます ([適用可能な場合](https://docs.stripe.com/connect/testing.md#creating-accounts))。 |

### エラーレスポンス

| パラメータ | 説明 |
| --- | --- |
| `error` | エラータイプごとの一意の[エラーコード](https://docs.stripe.com/connect/oauth-reference.md#post-token-error-codes)。 |
| `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** のみです。 |

#### API

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

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

アカウントへのアクセスの取り消しに使用されます。取り消し後は、貴社プラットフォームはダッシュボードから、または API 経由でこのアカウントにアクセスできなくなります。このアカウントは引き続き自身のダッシュボードから自身のデータと機能にアクセスできます。

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

### リクエスト

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

#### curl

```bash
curl https://connect.stripe.com/oauth/deauthorize \
  -u <<YOUR_SECRET_KEY>>: \
  -d client_id="ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb" \
  -d stripe_user_id=acct_ON3nXtRQkhmUIQ
```

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

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

### レスポンス

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

### エラーレスポンス

| パラメータ | 説明 |
| --- | --- |
| `error` | エラータイプ別の一意の[エラーコード](https://docs.stripe.com/connect/oauth-reference.md#post-deauthorize-error-codes)。 |
| `error_description` | 人間が理解できるエラーの説明。 |

### エラーコード

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

#### ダッシュボード

### ダッシュボードを使用してアカウントを削除する

ダッシュボードのアカウントの詳細ページで、連結アカウントの連結を解除できます。ページ右上にあるオーバーフローメニュー (⋯) をクリックし、**アカウントを削除**を選択します。

このアクションにより、アカウントがプラットフォームから連結解除され、OAuth de-authorize エンドポイントと同じ方法でアクセスが取り消されます。プラットフォームからアカウントを削除すると、入金タイミングなど、アカウントのすべてのプラットフォーム制御が完全にリセットされます。アカウントを後で再連結した場合でも変更は復元されません。その他の変更はアカウントには影響せず、通常の Stripe アカウントとして機能します。