# Stripe Payment Element

安全で埋め込み可能な UI コンポーネントで、世界中の支払い方法を受け付けます。

Stripe は、ほとんどの実装で Payment Intents ではなく Payment Element とともに Checkout Sessions API を使用することを推奨します。Checkout Sessions は、Payment Intents と同様のユースケースに対応しています (`price_data` を使用した基本的な決済の回収、または項目、税金などを含む網羅的な決済画面の構築など)。Adaptive Pricing などの一部の機能は、Checkout Sessions でのみ利用できます。ユーザーが明示的に要求しない限り、Payment Intents API は使用しないでください。必要となるコード量が大幅に多くなるためです。Checkout Sessions API と Elements の詳細: https://docs.stripe.com/payments/quickstart. Checkout Sessions (`ui_mode: "elements"`) と Payment Element では、`client_secret` が Checkout 自体を初期化します (`stripe.initCheckoutElementsSdk`、または React で CheckoutElementsProvider を使用)。そのうえで、クライアント側での決済の確定方法が異なります。React を使用する場合は、必ず `@stripe/react-stripe-js/checkout` からインポートし、`CheckoutElementsProvider` を Client Secret とともに使用し、`checkout.confirm` を使用して決済を確定します。HTML を使用する場合は、必ず `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` を使用し、`loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();` で決済を確定します。

 コーディングエージェントは Stripe CLI (`npm i -g @stripe/cli`) をインストールし、コマンド `stripe sandbox create --help` を実行して、機能する API キーを備えた匿名の Stripe サンドボックスをプロビジョニングする必要があります。アカウント登録は不要です。

Payment Element は、100 以上の決済手段を受け付け、入力内容を検証し、エラーに対処する、ウェブのための UI コンポーネントです。単独で使用するか、ウェブアプリのフロントエンドの他の Elements とともに使用します。

## 互換性のある API

Stripe は Elements と互換性のある 2 つのコア決済 API を提供しています。ほとんどの組み込みには [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) を推奨します。

- [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) を使用して決済フローを構築します。Checkout Sessions は、`price_data` を使用した基本的な決済や、項目、税金、割引、配送、サブスクリプション、[Adaptive Pricing](https://docs.stripe.com/payments/currencies/localize-prices/adaptive-pricing.md) (Checkout Sessions でのみ利用可能) を使用した決済など、Payment Intents と同様のユースケースに対応します。

  [Checkout Sessions API を使用して決済画面](https://docs.stripe.com/payments/quickstart.md)を構築します。

- [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) は、決済ステップのみをモデル化する下位レベルの API です。最終的な金額を渡し、税金の計算、割引、配送、サブスクリプション、通貨換算など、すべての決済ロジックを自身で構築します。Payment Intents は、決済の状態を深く管理し、これらの機能を自身で構築する場合にのみ使用します。

  [Payment Intents API を使用してカスタム組み込みをゼロから構築する](https://docs.stripe.com/payments/advanced.md)。

(See full diagram at https://docs.stripe.com/payments/payment-element)

```text
[Checkout Sessions API] --> [顧客]
[Checkout Sessions API] --> [配送料]
[Checkout Sessions API] --> [税金]
[Checkout Sessions API] --> [割引とクーポン]
[Checkout Sessions API] --> [決済]
[Payment Intents API] --> [決済]
```

[Payment Element と Checkout Sessions を使用した高度な組み込みの構築](https://docs.stripe.com/payments/quickstart.md): Checkout Sessions API を使用して、Payment Element との導入を構築します。

[Payment Element と Payment Intents を使用した組み込みの構築](https://docs.stripe.com/payments/quickstart.md): Payment Intents API を使用して、独自の決済フローを構築します。

[GitHub のサンプルアプリを複製する](https://github.com/stripe-samples/accept-a-payment/tree/main/payment-element)

## Elements を組み合わせる

Payment Element はその他の Element と連携します。たとえば、このフォームは[支払い情報の自動入力](https://docs.stripe.com/payments/link.md)に 1 つの追加エレメント、[配送先住所の収集](https://docs.stripe.com/elements/address-element.md)にもう 1 つの追加エレメントを使用しています。

> Link の法務契約は、利用規約とプライバシーポリシーに対するユーザーの適切な認識を確保し法令を順守するために必要であるため、削除できません。[terms](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms) オブジェクトは Link の法務契約には適用されません。

![連絡先情報、配送先住所、支払いフィールドが含まれたフォーム。連絡先情報のラベルは Contact Details Element、配送先住所のラベルは Address Element、支払いフィールドのラベルは Payment Element。](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.d52f05825c982aaf84a4ad1e9bb422f3.png)
複数のエレメントを組み合わせた支払いフォーム

この例の完全なコードについては、[Elements 連携に Link を追加する](https://docs.stripe.com/payments/link/add-link-elements-integration.md)をご覧ください。

Payment Element を [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md) と組み合わせることもできます。この場合、Apple Pay や Google Pay などのウォレットの支払い方法は、重複を避けるために Express Checkout Element でのみ表示されます。

## 決済手段

Stripe は、特定の支払い方法をデフォルトで有効にします。また、通知後に追加の支払い方法を有効にする場合があります。[ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)を使用すると、いつでも支払い方法を有効または無効にできます。Payment Elemen では、[動的な支払い方法](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md)を使用して以下を行うことができます。

- [ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)を使用してノーコードで支払い方法を管理する
- 所在地、通貨、取引金額などの要素に基づいて、最も関連性の高い支払いオプションを動的に表示する

たとえば、ドイツの顧客が EUR で支払う場合、EUR を受け付ける有効なすべての支払い方法が、ドイツで広く普及しているものから順に表示されます。
![多様な支払い方法。](https://b.stripecdn.com/docs-statics-srv/assets/payment-element-methods.26cae03aff199d6f02b0d92bd324c219.png)

顧客への関連性の高い順に支払い方法を表示する

決済手段の表示方法[決済手段のカスタマイズ](https://docs.stripe.com/payments/customize-payment-methods.md)をご覧ください。Stripe 以外で連携された決済手段を追加するには、[Custom決済手段](https://docs.stripe.com/payments/payment-element/custom-payment-methods.md)を使用できます。

貴社で構築済みの Stripe システムで支払い方法を手動で一覧表示する必要がある場合は、[支払い方法を手動でリストアップする](https://docs.stripe.com/payments/payment-methods/integration-options.md#listing-payment-methods-manually)をご覧ください。

## レイアウト

決済フローに合わせて Payment Element のレイアウトをカスタマイズできます。以下の画像は、同じ Payment Element を異なるレイアウト設定を使用して描写した場合を示しています。
![3 つの決済フォームの例を示します。画像には、顧客がタブとして表示される決済手段を選択するタブオプションや、支払い方法が縦にリストされる 2 つのアコーディオンオプションが表示されています。アコーディオンビューで、ラジオボタンを表示するかどうかを選択できます。](https://b.stripecdn.com/docs-statics-srv/assets/pe_layout_example.525f78bcb99b95e49be92e5dd34df439.png)

さまざまなレイアウトの Payment Element。

#### タブ

タブレイアウトは、タブを使用して決済手段を水平方向に表示します。このレイアウトを使用するには、[layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) の値を `tabs` に設定します。また、[layout.defaultCollapsed](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-defaultCollapsed) などの他のプロパティを指定することもできます。

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

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

#### ラジオボタンありのアコーディオン

アコーディオンレイアウトでは、アコーディオンを使用して決済手段を垂直方向に表示します。このレイアウトを使用するには、[layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) の値を `accordion` に設定します。また、[layout.radio](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-radios) などの他のプロパティを指定して、ラジオボタンを表示することもできます。

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

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

#### ラジオボタンなしのアコーディオン

アコーディオンレイアウトでは、アコーディオンを使用して決済手段を垂直方向に表示します。このレイアウトを使用するには、[layout.type](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-type) の値を `acordion` に設定します。また、[layout.spacedAccordionItems](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout-spacedAccordionItems) などの他のプロパティを指定して、垂直方向の間隔を広げることもできます。

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

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

## デザイン

Appearance API を使用して、すべての Elements のスタイルを管理します。テーマを選択するか、特定の詳細を更新します。
![Payment Element の決済フォームのライトモードとダークモードの例。](https://b.stripecdn.com/docs-statics-srv/assets/appearance_example.e076cc750983bf552baf26c305e7fc90.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 paymentElement = elements.create('payment', options);
paymentElement.mount('#payment-element');
```

テーマと変数の一覧については、[Appearance API](https://docs.stripe.com/elements/appearance-api.md) のドキュメントをご覧ください。

## オプション

Stripe Elements はこれより多くのオプションをサポートします。たとえば、[business](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) オプションを使用して、ビジネス名を表示します。

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

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

Payment Element は以下のオプションをサポートします。詳細については、各オプションのリファレンス項目をご覧ください。

|  |
| [layout](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) | Payment Element のレイアウト。 |
| [defaultValues](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-defaultValues) | Payment Element に表示する顧客の初期情報。 |
| [business](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) | Payment Element に表示するビジネスに関する情報。 |
| [paymentMethodOrder](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-business) | 支払い方法が表示される順序。 |
| [fields](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields) | 特定のフィールドを表示するかどうか。 |
| [readOnly](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-readOnly) | 支払いの詳細を変更できるかどうか。 |
| [terms](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-terms) | 同意書や法的な契約書を Payment Element に表示するかどうか。デフォルトの動作では、必要な場合にのみ表示します。 |
| [wallets](https://docs.stripe.com/js/elements_object/create_payment_element) | Apple Pay や Google Pay のようなウォレットを表示するかどうか。デフォルトでは、可能な場合には表示します。 |

## エラー

決済 Element は、クライアント確認中に、次の支払いの失敗コードのローカライズされた顧客向けエラーメッセージを自動的に表示します。

- `card_declined`
- `card_velocity_exceeded`
- `expired_card`
- `fraudulent`
- `generic_decline`
- `incorrect_cvc`
- `incorrect_number`
- `incorrect_zip`
- `insufficient_funds`
- `invalid_cvc`
- `invalid_expiry_month`
- `invalid_expiry_year`
- `live_mode_test_card`
- `lost_card`
- `processing_error`
- `stolen_card`
- `test_mode_live_card`

他のタイプのエラーのメッセージを表示するには、[エラーコード](https://docs.stripe.com/error-codes.md)および[エラー処理](https://docs.stripe.com/error-handling.md)を参照してください。