# 物理カードの住所の確認

物理カードの住所の確認機能を有効化および管理する方法をご紹介します。

Stripe Issuing では、対象の受取人に物理カードが正しく配送されるようにするために、適切な形式の正確な配送先住所が必要です。無効な住所に送付されたカードは Stripe に返送されますが、配送の試行と最終的な返送が完了するまでに 2 週間以上かかる場合があります。また、カードの返送によって業務負荷の追加、全体的なコストの増加、カード保有者の物理カードの受け取りの遅延が発生することもあります。

配送に成功する可能性を最大化するために、Stripe の Cards API には構築済みの住所の正規化と確認が含まれています。Stripe は指定された配送先住所をサードパーティーの住所データベースと比較して、住所の問題を特定または修正します。

## 住所の正規化

正規化では、住所が配送先の国の基準に従っていることを確認しながら、明らかな住所の誤りを修正します。

以下に正規化の例を示します。

### 確実に正しくフォーマット設定するための住所の正規化

```json
// Before
"shipping": {
  "address": {
    "line1": "354 Oyster Point Blvd South San Francisco, CA 94080", // incorrectly formatted line1
    "city": "South San Francisco",
    "postal_code": "94080",
    "state": "CA",
    "country": "US"
  }
}

// After
"shipping": {
  "address": {
    "line1": "354 OYSTER POINT BLVD",
    "city": "SOUTH SAN FRANCISCO",
    "postal_code": "94080",
    "state": "CA",
    "country": "US"
  }
}
```

### 既存の確認済み住所との照合で見つかった修正を適用するための住所の修正

```json
// Before
"shipping": {
  "address": {
    "line1": "354 Oyster Point",
    "city": "South San Francisco",
    "postal_code": "94080",
    "state": "NM", // incorrect state with an available correction
    "country": "US"
  }
}

// After
"shipping": {
  "address": {
    "line1": "354 OYSTER POINT BLVD", // added BLVD suffix
    "city": "SOUTH SAN FRANCISCO",
    "postal_code": "94080",
    "state": "CA", // corrected state
    "country": "US"
  }
}
```

正規化された住所は [address validation](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-shipping-address_validation) ハッシュに含まれます。このハッシュは、住所の正規化を有効にして法人カードの作成またはカードの配送先住所の更新に成功した後で返されます。

### 住所検証のサンプル

```json
"shipping": {
  // address supplied during card creation
  "address": {
    "line1": "354 Oyster Point Blvd South San Francisco, TX 94080",
    "city": "South San Francisco",
    "postal_code": "94080",
    "state": "TX",
    "country": "US"
  },
  // address validation hash
  "address_validation": {
    // the normalized address
    "normalized_address": {
      "line1": "354 OYSTER POINT BLVD",
      "city": "SOUTH SAN FRANCISCO",
      "state": "CA",
      "postal_code": "94080",
      "country": "US"
    },
    "mode": "validation_and_normalization",
    "result": "likely_deliverable"
  }
}

```

## 住所の確認

確認では、既存の確認済みの住所と照合することで、その住所が配達可能であるかが判断されます。確認は正規化の適用後に行われます。

この確認結果は住所確認ハッシュに含まれます。使用された[住所確認モード](https://docs.stripe.com/api/issuing/cards/object.md#issuing_card_object-shipping-address_validation-mode)によっては、API エラーが発生する場合があります。

| 結果 | 説明 |
| --- | --- |
| `likely_deliverable` | サードパーティーのデータベースで一部または完全に一致する住所が見つかる場合、住所は配送できる可能性が高いと見なされます。 |
| `likely_undeliverable` | サードパーティーのデータベースで一致または部分的に一致する住所が見つからない場合、住所は配送できない可能性が高いと見なされます。 |
| `indeterminate` | 住所が配送可能であるかを確認できませんでした。 |

たとえば、前の例では `likely_deliverable` の確認結果が示されています。

```json
"address_validation": {
  // the normalized address
  "normalized_address": {
    "line1": "354 OYSTER POINT BLVD",
    "city": "SOUTH SAN FRANCISCO",
    "state": "CA",
    "postal_code": "94080",
    "country": "US"
  },
  "mode": "validation_and_normalization",
  // the result showing that address was validated to be likely deliverable
  "result": "likely_deliverable"
}
```

## 住所確認モードを指定して住所確認機能を管理する

Cards API は 3 つの住所確認モードに対応しており、これは法人カードの作成時またはカードの配送の更新時に、必要に応じて [address_validation](https://docs.stripe.com/api/issuing/cards/create.md#create_issuing_card-shipping-address_validation) パラメーターで指定できます。

| モード | 説明 |
| --- | --- |
| `validation_and_normalization` | フルフィルメントの実行に送り出す前にカードの配送先住所の確認と正規化を行います。Stripe は住所に対して適切な修正の自動適用とフォーマット設定を試行してから、配送可能であるかどうかを判定します。カードの配送先住所が配送可能ではないと見込まれる場合は API リクエストのエラーが発生します。 |
| `normalization_only` | フルフィルメントの実行に送り出す前にカードの配送先住所の正規化を行い、必要に応じて住所に修正を加えてフォーマット設定を適用します。住所が配送可能であるかどうかの確認は行われず、API リクエストのエラーも発生しません。 |
| `disabled` | 正規化や配送可能であるかどうかの確認を行うことなく、指定どおりの住所を使用してカードを配送します。これは、住所が正しいことを認識しているか、他の方法で確認している場合にのみ推奨されます。 |

住所確認のモードには `validation_and_normalization` を使用します。シナリオに応じて、代替のモードも用意されています。

- `disabled`: カードが誤ってブロックされたと思われる場合。
- `正規化のみ`: API エラーを最小限に抑えつつ、正規化のメリットも得たい場合に使用します。指定がない場合のデフォルトは `validation_and_normalization` です。

### 確認と正規化

カードは確認済みの正規化された住所を使用して配送されます。住所が配送可能であるかどうかの確認が行われ、配送できない可能性が高い場合は API エラーが発生します。Stripe では、このモードを使用して、住所が配送可能であるかを確認することを強くお勧めします。

```curl
curl https://api.stripe.com/v1/issuing/cards \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "cardholder={{ISSUINGCARDHOLDER_ID}}" \
  -d type=physical \
  -d currency=usd \
  -d "shipping[name]=Jenny Rosen" \
  -d "shipping[address][line1]=1234 Fake St" \
  -d "shipping[address][city]=Fake City" \
  -d "shipping[address][state]=NY" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][postal_code]=94111" \
  -d "shipping[address_validation][mode]=validation_and_normalization"
```

```json
{
  "error": {
    "message": "The address is undeliverable based on given inputs. Please ensure that the address was inputted correctly and can be delivered to."
  }
}
```

### 正規化のみ

カードは正規化された住所を使用して配送されます。住所が配送可能であるかどうかの確認は行われず、配送できない可能性が高い場合でも API リクエストのエラーは発生しません。

```curl
curl https://api.stripe.com/v1/issuing/cards \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "cardholder={{ISSUINGCARDHOLDER_ID}}" \
  -d type=physical \
  -d currency=usd \
  -d "shipping[name]=Jenny Rosen" \
  -d "shipping[address][line1]=1234 Fake St" \
  -d "shipping[address][city]=Fake City" \
  -d "shipping[address][state]=NY" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][postal_code]=94111" \
  -d "shipping[address_validation][mode]=normalization_only"
```

```json
# Example response
{
  "id":  "{{CARD_ID}}",
  "object": "issuing.card",
  "shipping": {
    // address supplied during card creation
    "address": {
      "line1": "1234 Fake Street",
      "city": "Fake city",
      "postal_code": "94111",
      "state": "NY",
      "country": "US"
    },
    // address validation information
    "address_validation": {
      // the card will be shipped with this address
      "normalized_address": {
        "line1": "1234 FAKE ST",
        "city": "FAKE CITY",
        "state": "NY",
        "postal_code": "94111",
        "country": "US"
      },
      "mode": "normalization_only",
      "result": "likely_undeliverable"
    },
    // other fields...
  },
  // other fields...
}

```

### 無効

このモードでは、正規化や配送可能であるかどうかの確認を行うことなく、指定どおりの住所を使用してカードを配送します。正規化された住所と確認結果は返されません。これは、住所が正しいことを認識しているか、他の方法で確認している場合にのみ推奨されます。

```curl
curl https://api.stripe.com/v1/issuing/cards \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "cardholder={{ISSUINGCARDHOLDER_ID}}" \
  -d type=physical \
  -d currency=usd \
  -d "shipping[name]=Jenny Rosen" \
  -d "shipping[address][line1]=1234 Fake St" \
  -d "shipping[address][city]=Fake City" \
  -d "shipping[address][state]=NY" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][postal_code]=94111" \
  -d "shipping[address_validation][mode]=disabled"
```

```json
// Example response
{
  "id":  "{{CARD_ID}}",
  "object": "issuing.card",
  "shipping": {
    // address supplied during card creation
    "address": {
      "line1": "1234 Fake Street",
      "city": "Fake city",
      "postal_code": "94111",
      "state": "NY",
      "country": "US"
    },
    // address validation information
    "address_validation": {
      "mode": "disabled"
    },
    // other fields...
  },
  // other fields...
}
```

## 住所確認をカード作成フローと連携させる

以下に、フローを住所確認機能と連携する方法の例をいくつか紹介します。これらの例は、すべてを網羅したものではなく、連携の参考アイデアとして提供されています。

#### 同期によるカード作成

### 厳格な住所の確認

配送可能な確率を高める最適な方法は、住所の確認を決してバイパスせず、顧客に常に配送可能な住所の提出を依頼することです。

厳格な住所の確認フロー (See full diagram at https://docs.stripe.com/issuing/cards/physical/address-validation)

```text
[顧客] -- 配送不能な住所が指定された配送先の詳細を送信して、カードを注文する --> [サイト]
[サイト] -- validation_and_normalization モードで Card (カード) を作成する --> [Stripe]
[Stripe] -- likely_undeliverable と判断されるカードの配送先住所 --> [Stripe]
[Stripe] -- エラー 400 の配送不能な配送先住所のレスポンスを送信する --> [サイト]
[サイト] -- 無効な住所の修正をユーザーに求める --> [顧客]
[顧客] -- 配送先住所を修正して再送信する --> [サイト]
[サイト] -- validation_and_normalization モードで Card (カード) を作成する --> [Stripe]
[Stripe] -- likely_deliverable と判断されるカードの配送先住所 --> [Stripe]
[Stripe] -- Card (カード) を返す --> [サイト]
```

### 住所の提案候補

提案による住所候補とユーザーが指定した住所のどちらかを選択するようにユーザーに求めることは一般的なフローです。Stripe の住所確認機能を使用して自社で構築できます。

住所の候補提案フロー (See full diagram at https://docs.stripe.com/issuing/cards/physical/address-validation)

```text
[顧客] -- 配送先の詳細を送信してカードを注文する --> [サイト]
[サイト] -- validation_and_normalization モードで Card (カード) を作成する --> [Stripe]
[Stripe] -- カード配送先住所が正規化され、likely_deliverable と判断される --> [Stripe]
[Stripe] -- 確認済みの正規化された住所が設定された新しい Card (カード) を返す --> [サイト]
[サイト] -- カードの normalized_address を使用して、より適切な住所を提案する --> [顧客]
[顧客] -- 住所の選択を確認する --> [サイト]
[サイト] -- 元の住所が選択された場合に、disabled モードを使用して、Card (カード) を元の住所で更新する --> [Stripe]
[Stripe] -- 更新された Card (カード) を返す --> [サイト]
```

### ゆるやかな住所確認

提出された住所の確認をユーザーに依頼することで、配送不能住所のエラーを適切に処理できます。`disabled` 住所確認モードを活用することにより、顧客は、住所が正しいことが分かっていれば、それほどの負担なく、カードを注文できます。

ゆるやかな住所確認フロー (See full diagram at https://docs.stripe.com/issuing/cards/physical/address-validation)

```text
[顧客] -- 配送先の詳細を送信してカードを注文する --> [サイト]
[サイト] -- validation_and_normalization モードで Card (カード) を作成する --> [Stripe]
[Stripe] -- likely_undeliverable と判断されるカードの配送先住所 --> [Stripe]
[Stripe] -- エラー 400 の配送不能な配送先住所のレスポンスを送信する --> [サイト]
[サイト] -- 指定された住所が正しいかどうかを尋ねる確認を表示します --> [顧客]
[顧客] -- 送信された住所が正しいことを確認する --> [サイト]
[サイト] -- disabled モードで Card (カード) を作成する --> [Stripe]
[Stripe] -- Card (カード) を返す --> [サイト]
```

#### 非同期のカード作成

### 非同期の住所確認

下記のフローは、システムを中断することなく、配送不能の住所を処理する方法を示しています。

`normalization_only` モードを活用することにより、カードは引き続き正常に作成され、レスポンスで住所の確認結果が示されます。必要に応じて、これらの結果を別のフローで使用して、住所に問題がある可能性を顧客に通知することができます。

非同期の住所修正フロー (See full diagram at https://docs.stripe.com/issuing/cards/physical/address-validation)

```text
[顧客] -- 配送先の詳細を送信してカードを注文する --> [サイト]
[サイト] -- カード注文確認ページにリダイレクトする --> [顧客]
[サイト] -- normalization_only モードで Card (カード) を作成する --> [Stripe]
[Stripe] -- likely_undeliverable と判断されるカードの配送先住所 --> [Stripe]
[Stripe] -- レスポンスに likely_undeliverable の住所を指定して Card (カード) を返す --> [サイト]
[サイト] -- (オプション) 住所に問題がある可能性を顧客に通知し、必要に応じて更新する --> [顧客]
[顧客] -- 修正後の新しい住所を送信する --> [サイト]
[サイト] -- validation_and_normalization モードを使用して、新しい住所で Card (カード) を更新する --> [Stripe]
[Stripe] -- likely_deliverable と判断されるカードの配送先住所 --> [Stripe]
[Stripe] -- 更新された Card (カード) を返す --> [サイト]
```

## 住所の確認をテストする

`line1` にマジック値を指定して、テスト環境で特定の検証条件をトリガーできます。`city`、`state`、および `postal_code` 引数に正当な値を渡す必要があります。

| 値 | タイプ |
| --- | --- |
| `address_valid` | テスト成果物の配送先住所を使用してリクエストを送信します。 |
| `address_invalid` | テスト用の配送不能な配送先住所を使用してリクエストを送信します。 |

```curl
curl https://api.stripe.com/v1/issuing/cards \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "cardholder={{ISSUINGCARDHOLDER_ID}}" \
  -d type=physical \
  -d currency=usd \
  -d "shipping[name]=Jenny Rosen" \
  -d "shipping[address][line1]=address_invalid" \
  -d "shipping[address][city]=San Francisco" \
  -d "shipping[address][state]=CA" \
  -d "shipping[address][country]=US" \
  -d "shipping[address][postal_code]=94111" \
  -d "shipping[address_validation][mode]=validation_and_normalization"
```