# 連結アカウント、カード保有者、カード

Stripe Connect でカード保有者とカードを作成し、管理する方法をご紹介します。

連結アカウントは法人に相当します。カード保有者はそうした法人に関連付けられている個人を表します。1 つの連結アカウントに複数のカード保有者を設定できます。たとえば、中小企業の連結アカウントで複数のカードを設定して、オーナーと従業員が使用できるようにすることができます。カード保有者を作成したら、バーチャルカードか物理カードを保有者に発行します。
連結アカウントのカード保有者とカード (See full diagram at https://docs.stripe.com/issuing/connect/cardholders-and-cards)
## カード保有者を作成する

[Cardholder](https://docs.stripe.com/api/issuing/cardholders/object.md) を作成するには、[Cardholder API](https://docs.stripe.com/api/issuing/cardholders/create.md) を使用して必要な情報を入力します。[デジタルウォレット](https://docs.stripe.com/issuing/cards/digital-wallets.md)を使用する場合は、有効な電話番号とメールアドレスが必要ですが、法人カードの場合は任意です。

> Connect プラットフォームは、`Stripe-Account` ヘッダーと連結アカウントのアカウント ID を含めて、連結アカウントの代わりに API コールを実行します。

| フィールド   | パラメーター         | 説明                                                                                                                                   |
| ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 請求先情報   | `billing`      | カード保有者の請求先住所 (通常はビジネスのメインの住所)。私書箱、高速道路の契約ボックス、私設郵便受けの住所は使用できませんが、カードの配送先住所としては使用できます。                                                |
| タイプ     | `type`         | カード保有者が `company` か `individual` か。ガイダンスについては、[カード保有者の種類を選択する](https://docs.stripe.com/issuing/other/choose-cardholder.md)を参照してください。 |
| 電話番号    | `phone_number` | デジタルウォレットを使用する場合は必須                                                                                                                  |
| メールアドレス | `email`        | カード保有者のメールアドレス。デジタルウォレットを使用する場合は必須                                                                                                   |

```curl
curl https://api.stripe.com/v1/issuing/cardholders \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d "name=Jenny Rosen" \
  --data-urlencode "email=jenny.rosen@example.com" \
  --data-urlencode "phone_number=+18008675309" \
  -d status=active \
  -d type=individual \
  -d "individual[first_name]=Jenny" \
  -d "individual[last_name]=Rosen" \
  -d "individual[dob][day]=1" \
  -d "individual[dob][month]=11" \
  -d "individual[dob][year]=1981" \
  -d "billing[address][line1]=510 Townsend Street" \
  -d "billing[address][city]=San Francsico" \
  -d "billing[address][state]=CA" \
  -d "billing[address][postal_code]=94111" \
  -d "billing[address][country]=US"
```

Stripe は指定された情報が格納された Cardholder オブジェクトを返し、`issuing_cardholder.created` [Webhook](https://docs.stripe.com/webhooks.md) イベントを送信します。

`Cardholder` を作成したら、変更が必要なパラメーターを指定して [カード保有者の更新](https://docs.stripe.com/api/issuing/cardholders/update.md)エンドポイントを呼び出します。コールが成功すると、更新後の `Cardholder` オブジェクトが返されます。

カード会員は、初期設定では `active` [ステータス](https://docs.stripe.com/api/issuing/cardholders/update.md#update_issuing_cardholder-status)です。これは、プラットフォームがカード会員を有効化することを意味し、その結果、当該カード会員に紐付くすべてのカードがオーソリを承認できるようになります。

Stripe には、法務および規制ガイドラインに従ってカード会員の本人確認情報をスクリーニングする義務があります。これにより、カード保有者のステータスが `active` であっても、その会員の属性に基づく承認がブロックされる可能性があります。[ウォッチリストレビュー](https://support.stripe.com/questions/issuing-watchlist-reviews)の詳細はこちらをご覧ください。

カード会員を更新することで、`status` を `inactive` に変更することができます。Cardholder が inactive ということは、紐付けられたカードについて、`cardholder_inactive` という理由ですべての承認が拒否されるということです。

## カードを作成する

`Cardholder` を作成したら、[Cards API](https://docs.stripe.com/api/issuing/cards/create.md) を使用してカードを発行します。

[Card](https://docs.stripe.com/api/issuing/cards/object.md) オブジェクトは[物理カード](https://docs.stripe.com/issuing/cards/physical.md)および[バーチャルカード](https://docs.stripe.com/issuing/cards/virtual.md)を表します。物理カードを作成するには配送先住所が必要です。[追加の引数](https://docs.stripe.com/issuing/cards/physical.md)を指定して配送用の梱包と配送サービスを指定できます。

| カード保有者 | `cardholder` | カード保有者の ID                                                                |
| ------ | ------------ | ------------------------------------------------------------------------- |
| 通貨     | `currency`   | 3 文字 (小文字) の ISO 通貨コード。対応可能な通貨は、アメリカの `usd`、イギリスの `gbp`、ユーロ圏諸国の `eur` です。 |
| タイプ    | `type`       | `physical` または `virtual` のいずれか                                            |

次の呼び出しは、指定されたカード保有者に関連付けられたバーチャルカードを発行する例です。

```curl
curl https://api.stripe.com/v1/issuing/cards \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d "cardholder={{ISSUINGCARDHOLDER_ID}}" \
  -d currency=usd \
  -d type=virtual
```

Stripe は、作成後すぐに `Card` オブジェクトを返し、`issuing_card.created` [Webhook](https://docs.stripe.com/webhooks.md) イベントを送信します。

## カードを有効にする

[オーソリ](https://docs.stripe.com/issuing/purchases/authorizations.md)が承認されるには、カードが有効化されている必要があります。

カードの作成時にステータスを指定しない場合は、デフォルトのステータス `inactive` が設定されます。[カードの更新](https://docs.stripe.com/api/issuing/cards/update.md)エンドポイントでステータスが変更されるまで、カードのステータスは `inactive` のままになります。

カードを有効化する方法

```curl
curl https://api.stripe.com/v1/issuing/cards/{{CARD_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d status=active
```

## カードを無効にする

[カード更新](https://docs.stripe.com/api/issuing/cards/update.md)エンドポイントで `status` を `inactive` に設定すると、カードを無効化できます。このようにするとそのカードでは「新たな」オーソリを承認できなくなります。ただし、ステータスを `inactive` に設定する前に開始されたオーソリは承認できます。新たなオーソリを承認するには、カードのステータスを `active` に変更する必要があります。

```curl
curl https://api.stripe.com/v1/issuing/cards/{{CARD_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d status=inactive
```

[オーソリを管理する](https://docs.stripe.com/issuing/purchases/authorizations.md)についてもっと知る。

## カードをキャンセルする

[カード更新](https://docs.stripe.com/api/issuing/cards/update.md)エンドポイントでステータスを `canceled` に変更すると、カードをキャンセルすることができます。キャンセルされたステータスは最終決定であり、取り消すことはできません。`canceled` ステータスが指定されたカードで新たなオーソリを承認することはできません。ただし、ステータスを `canceled` に設定する前に開始されたオーソリは承認することができます。

```curl
curl https://api.stripe.com/v1/issuing/cards/{{CARD_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d status=canceled
```

### カード会員のリスト

[Cardholders API](https://docs.stripe.com/api/issuing/cards/list.md) の GET リクエストを実行し、特定の `Stripe-Account` をヘッダーに渡すと、連結アカウントに関連付けられているカード保有者を検索できます。

```curl
curl https://api.stripe.com/v1/issuing/cardholders \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}"
```

成功すると、レスポンスでカード保有者のリストが返されます。

```json
{
  "object": "list",
  "data": [
    {
      "id": "{{CARDHOLDER_ID}}",
      "object": "issuing.cardholder",
      "billing": {
        "address": {
          "city": "San Francisco",
          "country": "US",
          "line1": "510 Townsend Street",
          "line2": null,
          "postal_code": "94111",
          "state": "CA"
        }
      },
      "company": null,
      "created": 1657144326,
      "email": "jenny.rosen@example.com",
      "individual": null,
      "livemode": false,
      "metadata": {},
      "name": "Jenny Rosen",
      "phone_number": "+18008675309",
      "requirements": {
        "disabled_reason": null,
        "past_due": []
      },
      "spending_controls": {
        "allowed_categories": [],
        "blocked_categories": [],
        "spending_limits": [],
        "spending_limits_currency": null
      },
      "status": "active",
      "type": "individual"
    },
    {
      "id": "{{CARDHOLDER_ID}}",
      "object": "issuing.cardholder",
      "billing": {
        "address": {
          "city": "San Francisco",
          "country": "US",
          "line1": "510 Townsend Street",
          "line2": null,
          "postal_code": "94111",
          "state": "CA"
        }
      },
      "company": null,
      "created": 1656537695,
      "email": "jenny.rosen@example.com",
      "individual": null,
      "livemode": false,
      "metadata": {},
      "name": "Jenny Rosen",
      "phone_number": "+18008675309",
      "requirements": {
        "disabled_reason": null,
        "past_due": []
      },
      "spending_controls": {
        "allowed_categories": [],
        "blocked_categories": [],
        "spending_limits": [],
        "spending_limits_currency": null
      },
      "status": "active",
      "type": "individual"
    }
  ],
  "has_more": false,
  "url": "/v1/issuing/cardholders"
}
```

## カードをリストする

[Cards API](https://docs.stripe.com/api/issuing/cards/list.md) の GET リクエストを実行し、特定の `Stripe-Account` をヘッダーに渡すと、連結アカウントで作成されているカードのリストを表示できます。

```curl
curl https://api.stripe.com/v1/issuing/cards \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}"
```

成功すると、カードのリストが返されます。

```json
{
  "object": "list",
  "data": [
    {
      "id": "{{CARD_ID}}",
      "object": "issuing.card",
      "brand": "Visa",
      "cancellation_reason": null,
      "cardholder": {
        "id": "{{CARDHOLDER_ID}}",
        "object": "issuing.cardholder",
        "billing": {
          "address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "510 Townsend Street",
            "line2": null,
            "postal_code": "94111",
            "state": "CA"
          }
        },
        "company": null,
        "created": 1656537695,
        "email": "jenny.rosen@example.com",
        "individual": null,
        "livemode": false,
        "metadata": {},
        "name": "Jenny Rosen",
        "phone_number": "+18008675309",
        "requirements": {
          "disabled_reason": null,
          "past_due": []
        },
        "spending_controls": {
          "allowed_categories": [],
          "blocked_categories": [],
          "spending_limits": [],
          "spending_limits_currency": null
        },
        "status": "active",
        "type": "individual"
      },
      "created": 1656537950,
      "currency": "usd",
      "exp_month": 5,
      "exp_year": 2025,
      "last4": "0021",
      "livemode": false,
      "metadata": {},
      "pin": null,
      "replaced_by": null,
      "replacement_for": null,
      "replacement_reason": null,
      "shipping": null,
      "spending_controls": {
        "allowed_categories": [
          "car_rental_agencies"
        ],
        "blocked_categories": null,
        "spending_limits": [
          {
            "amount": 8000,
            "categories": [],
            "interval": "per_authorization"
          }
        ],
        "spending_limits_currency": "usd"
      },
      "status": "active",
      "type": "virtual",
      "wallets": {
        "apple_pay": {
          "eligible": true,
          "ineligible_reason": null
        },
        "google_pay": {
          "eligible": true,
          "ineligible_reason": null
        },
        "primary_account_identifier": null
      }
    },
    {
      "id": "{{CARD_ID}}",
      "object": "issuing.card",
      "brand": "Visa",
      "cancellation_reason": null,
      "cardholder": {
        "id": "{{CARDHOLDER_ID}}",
        "object": "issuing.cardholder",
        "billing": {
          "address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "510 Townsend Street",
            "line2": null,
            "postal_code": "94111",
            "state": "CA"
          }
        },
        "company": null,
        "created": 1656537695,
        "email": "jenny.rosen@example.com",
        "individual": null,
        "livemode": false,
        "metadata": {},
        "name": "Jenny Rosen",
        "phone_number": "+18008675309",
        "requirements": {
          "disabled_reason": null,
          "past_due": []
        },
        "spending_controls": {
          "allowed_categories": [],
          "blocked_categories": [],
          "spending_limits": [],
          "spending_limits_currency": null
        },
        "status": "active",
        "type": "individual"
      },
      "created": 1656537947,
      "currency": "usd",
      "exp_month": 5,
      "exp_year": 2025,
      "last4": "0013",
      "livemode": false,
      "metadata": {},
      "pin": null,
      "replaced_by": null,
      "replacement_for": null,
      "replacement_reason": null,
      "shipping": null,
      "spending_controls": {
        "allowed_categories": null,
        "blocked_categories": null,
        "spending_limits": [
          {
            "amount": 50000,
            "categories": [],
            "interval": "daily"
          }
        ],
        "spending_limits_currency": "usd"
      },
      "status": "active",
      "type": "virtual",
      "wallets": {
        "apple_pay": {
          "eligible": true,
          "ineligible_reason": null
        },
        "google_pay": {
          "eligible": true,
          "ineligible_reason": null
        },
        "primary_account_identifier": null
      }
    }
  ],
  "has_more": false,
  "url": "/v1/issuing/cards"
}
```

[Cards API](https://docs.stripe.com/api/issuing/cards/list.md) の GET リクエストに `cardholder` パラメーターを含めると、特定のカード保有者に関連付けられたカードのリストを表示できます。特定の `Stripe-Account` をヘッダーに渡して、カード保有者 ID を `cardholder` パラメーターに渡します。

```curl
curl -G https://api.stripe.com/v1/issuing/cards \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d "cardholder={{ISSUINGCARDHOLDER_ID}}"
```