# Connect OAuth リファレンス

このリファレンスでは、Connect で使用できる 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) プラットフォームでは、3 種類の[アカウントタイプ](https://docs.stripe.com/connect/accounts.md)が使用されます。

このページのコンテンツは、Standard アカウントにのみ適用されます。

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 をそれぞれ追加します。
1. 認証リクエストに `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。[アプリケーション設定](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`(オプション)(Standard のみ) | **read\_write** または **read\_only**。必要なアクセスのレベルによって異なります。Standard アカウントのデフォルトでは、**read\_only** に設定されています。**read\_only** は[拡張機能のみ指定可能](https://docs.stripe.com/connect/oauth-changes-for-standard-platforms.md)であることに注意してください。                                                                                                                                       |
| `state`(オプション)              | お客様に返される任意の文字列値。CSRF の対策に役立ちます。                                                                                                                                                                                                                                                                                                                                    |

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

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

| パラメータ                                                                   | 説明                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stripe_user[email]`(Recommended)                                       | ユーザのメールアドレス。有効なメール形式で入力してください。                                                                                                                                                                                                                                                     |
| `stripe_user[url]`(Recommended)                                         | ユーザーのビジネスの 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 コード](http://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 アカウントとして機能します。