# Address Element

Address Element を使用して詳細な請求先住所と配送先住所を収集します。

Address Element は詳細な住所を受け入れる埋め込み可能な UI コンポーネントです。配送先住所を収集する際や、税務上の目的などで詳細な請求先住所が必要な場合に使用してください。

| オプション | 説明 |
| --- | --- |
| **テーマ** | ドロップダウンを使用してテーマを選択するか、[Elements Appearance API](https://docs.stripe.com/elements/address-element.md#appearance)を使用してテーマをカスタマイズします。 |
| **デスクトップとモバイルのサイズ** | ドロップダウンを使用して、Address Element をマウントする親要素の最大ピクセル幅を設定します。750px (デスクトップ) または 320px (モバイル) に設定できます。 |
| **顧客の住所** | この[オプション](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale)を使用して、完全な場所を受け付ける場所を選択します。場所を変更すると UI 言語がローカライズされます。 |
| **電話番号** | この[オプション](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-fields-phone)を有効にすると、場所を入力したり、既存の連絡先を使用したりした場合に電話番号の収集を許可しましょう。 |
| **オートコンプリート** | この[オプション](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-autocomplete)を有効にして、決済時間の短縮、検証エラーの減少、組み込みの場所自動補完機能で購入率を増加させます。Stripe は右から左への場所形式を含む 236 種類の地域場所フォーマットをサポートしています。 |
| **連絡先** | この[オプション](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-contacts)を有効にすると、新しい住所を追加したり、既存の住所や電話番号を変更したりできます。 |

## 利用を開始する

Address Element は、Checkout エレメントの導入Checkout Sessions API 付き Elements) または高度な導入 (エレメントwith Payment Intents API) のいずれかで使用できます。[機能と利用可否を比較](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability)すれば、ユースケースに適した導入方法を確認できます。

[住所を収集する (Elements with Checkout Sessions API)](https://docs.stripe.com/payments/advanced/collect-addresses.md?payment-ui=embedded-components): Checkout エレメントの導入を使用すれば、住所を収集できます。

[住所を収集する (アドバンス統合)](https://docs.stripe.com/payments/advanced/collect-addresses.md?payment-ui=elements): アドバンス統合を使用してアドレスを収集します。

[サンプルアプリをクローンする (アドバンス統合)](https://github.com/stripe-samples/link)

## Address Element を作成する

Address Element を作成する際は、それを配送モードと請求モードのどちらで使用するかを指定します。

#### 配送モード

配送モードでは、Element には 2 つの機能があります。

- 配送先住所を収集します。
- それを請求先住所としても使用するオプションを顧客に提供します。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = { mode: 'shipping' };
const elements = stripe.elements({ clientSecret, appearance }); // 有効な実装では、これは、バックエンドが支払いの金額などの詳細を指定して渡す値です。詳細については、サンプル全体をご覧ください。
const addressElement = elements.create('address', options);
addressElement.mount('#address-element');
```

#### 請求モード

請求モードでは、Element は請求先住所の収集のみを行います。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = { mode: 'billing' };
const elements = stripe.elements({ clientSecret, appearance }); // 有効な実装では、これは、バックエンドが支払いの金額などの詳細を指定して渡す値です。詳細については、サンプル全体をご覧ください。
const addressElement = elements.create('address', options);
addressElement.mount('#address-element');
```

### その他のエレメントとともに住所 Element を使用する

ページに複数の Address Element (モードにつき 1 つ) を使用して、配送先住所と請求先住所の両方を収集できます。

配送先住所と請求先住所の両方を収集する必要があり、Address Element を 1 つのみ使用する場合は、配送モードで Address Element を使用し、請求先住所の収集には [Payment Element](https://docs.stripe.com/payments/payment-element.md) を使用します。

住所 Element を他の Element とともに使用すると、PaymentIntent または SetupIntent の確定時に一部の動作を自動で実行できます。PaymentIntent または SetupIntent の確定時に住所 Element の完全性が検証され、検証エラーが発生した場合はフィールドごとにエラーが表示されます。

## 住所を使用する

Address Element は [Payment](https://docs.stripe.com/payments/payment-element.md) または Express Checkout Element と自動的に連携します。購入者が住所と支払い方法を指定すると、Stripe は適切なフィールドに住所を設定して、それらを 1 つの *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) に結合します。

### 自動の動作

Element のデフォルトの動作はモードによって異なります。

#### 配送モード

配送モードでは、住所は以下のフィールドに保存されます。

- [shipping](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-shipping) フィールドに表示されます。
- 顧客がそれが請求書の住所でもあることを示している場合は、[billing_details](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-payment_method_data-billing_details) フィールドにも表示されます。

情報の組み合わせを有効にするには、この例のように、同じ `Elements` オブジェクトからすべての Element を作成します。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = { mode: 'shipping' };
const paymentElementOptions = { layout: 'accordion'};
const elements = stripe.elements({ clientSecret }); // 有効な実装では、これは、バックエンドが支払いの金額などの詳細を指定して渡す値です。詳細については、サンプル全体をご覧ください。
const addressElement = elements.create('address', options);
const paymentElement = elements.create('payment', paymentElementOptions);
addressElement.mount('#address-element');
paymentElement.mount('#payment-element');
```

#### 請求モード

請求モードでは、住所は [billing_details](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-payment_method_data-billing_details) フィールドに保存されます。

情報の組み合わせを有効にするには、この例のように、同じ `Elements` オブジェクトからすべての Element を作成します。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = { mode: 'billing' };
const paymentElementOptions = { layout: 'accordion'};
const elements = stripe.elements({ clientSecret }); // 有効な実装では、これは、バックエンドが支払いの金額などの詳細を指定して渡す値です。詳細については、サンプル全体をご覧ください。
const addressElement = elements.create('address', options);
const paymentElement = elements.create('payment', paymentElementOptions);
addressElement.mount('#address-element');
paymentElement.mount('#payment-element');
```

### カスタムの動作

通常は、Address Element のデフォルト動作で十分です。ただし、複雑な決済フローでは、顧客の入力に対するカスタムレスポンスの記述が必要になる場合があります。詳細については、[住所の入力をリッスン](https://docs.stripe.com/payments/advanced/collect-addresses.md) してください。

## オートコンプリート

顧客が住所にサポート対象の国を選択すると、オートコンプリートオプションが表示されます。Address Element では、次の国の住所をオートコンプリートできます。

- AU
- BE
- BR
- CA
- CH
- DE
- ES
- FR
- GB
- IE
- IN
- IT
- JP
- MX
- MY
- NL
- NO
- NZ
- PH
- PL
- RU
- SE
- SG
- TR
- US
- ZA

住所要素と支払い要素を一緒に使用すると、Stripe は設定を必要とせずにオートコンプリートを有効にします。これは、Stripe が提供する Google マップ API キーを使用して行われます。

> オートコンプリートを使用すると、[Google Maps Platform 利用規定](https://cloud.google.com/maps-platform/terms/aup)に準拠することに同意したことになります。このポリシーに違反した場合、オートコンプリートが無効になるか、必要に応じてその他の措置が講じられることがあります。

Address Element を単体で使用する場合は、Stripe アカウントとは別で管理するご自身の [Google Maps API Places Library キー](https://developers.google.com/maps/documentation/javascript/places)を使用する必要があります。キーを [autocomplete.apiKey](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-autocomplete-apiKey) オプションに渡します。

## Link で自動入力

[Link](https://docs.stripe.com/payments/link.md) は、有効化したオプションに対して決済および配送情報を保存し、自動入力します。例えば、Linkのカスタマーに保存済みの電話番号がある場合でも、電話番号の取得が有効になっているときにのみ Stripe は電話番号を自動入力します。既存の Link カスタマーが認証を行うと、Stripe は Address Element で配送先情報を自動入力します。
![複数の Elements を使用して決済フォームを作成する](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.d52f05825c982aaf84a4ad1e9bb422f3.png)

複数の Elements を使用して決済フォームを作成する

自動入力を有効にするには、この例のように、同じ `Elements` オブジェクトからすべての Element を作成します。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = { /* appearance */ };
const options = { mode: 'shipping' };
const paymentElementOptions = { layout: 'accordion'};
const elements = stripe.elements({ clientSecret }); // 有効な実装では、これは、バックエンドが支払いの金額などの詳細を指定して渡す値です。詳細については、サンプル全体をご覧ください。
const linkAuthElement = elements.create('linkAuthentication');
const addressElement = elements.create('address', options);
const paymentElement = elements.create('payment', paymentElementOptions);
linkAuthElement.mount('#link-auth-element');
addressElement.mount('#address-element');
paymentElement.mount('#payment-element');
```

## デザイン

Appearance API を使用して、すべての Elements のスタイルを管理できます。テーマを選択するか、特定の詳細を更新することができます。
![Address Element のライトモードとダークモードの例。](https://b.stripecdn.com/docs-statics-srv/assets/address_appearance_example.c7884ea763b05e5881d65ed2b2afadbc.png)

たとえば、「flat」のテーマを選択して、主要なテキストの色を上書きします。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');

const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};
const options = { /* options */ };
const elements = stripe.elements({ clientSecret, appearance }); // 有効な実装では、これは、バックエンドが支払いの金額などの詳細を指定して渡す値です。詳細については、サンプル全体をご覧ください。
const addressElement = elements.create('address', options);
addressElement.mount('#address-element');
```

テーマと変数の一覧については、[Elements with Checkout Sessions API 統合](https://docs.stripe.com/payments/checkout/customization/appearance.md?payment-ui=embedded-components)または[アドバンス統合](https://docs.stripe.com/elements/appearance-api.md)の Appearance API ドキュメントを参照してください。