# 埋め込みフォームを使用した実装を構築

このガイドでは、*Checkout Sessions* (A Checkout Session represents your customer's session as they pay for one-time purchases or subscriptions through Checkout. After a successful payment, the Checkout Session contains a reference to the Customer, and either the successful PaymentIntent or an active Subscription) で組み込みフォームを使用する方法を解説します。

## Stripe を設定する [サーバ側]

まず、[Stripe アカウントを作成する](https://dashboard.stripe.com/register)か[サインイン](https://dashboard.stripe.com/login)します。

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

アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリを使用します。

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```

## 決済手段を有効にする

デフォルトでは、Stripe は[決済手段の設定](https://dashboard.stripe.com/settings/payment_methods)を使用して、組み込みフォームに表示する決済手段を決定します。[payment_method_types](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_types) 属性を使用して、Checkout Session で特定の決済手段を設定することもできます。

## Checkout Session を作成する [サーバー側]

サーバーで Checkout Session を作成して決済フローを制御します。Checkout Session は、明細項目、配送オプション、決済に関するその他の設定を定義します。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d ui_mode=form \
  -d return_url={{RETURN_URL}}
```

組み込みフォームを実装するには、`ui_mode` を `form` に設定します。返された `CheckoutSession` オブジェクトには Client Secret が含まれており、クライアントはこれを使用して決済インターフェイスを安全に表示します。

[CheckoutSession](https://docs.stripe.com/api/checkout/sessions/create.md) で以下のオプションも設定できます。

- [automatic_tax](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-automatic_tax): 税金の自動計算を有効にする
- [billing_address_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-billing_address_collection): 請求先住所の回収
- [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email): 顧客のメールアドレスを事前入力します
- [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer): 既存の `Customer` オブジェクトから顧客データを事前入力します
- [name_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-name_collection): 顧客の法人名、個人名、またはその両方を収集します
- [shipping_address_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_address_collection): 配送先住所を収集する
- [shipping_options](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_options): 配送料金のオプションを指定する
- [submit_type](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-submit_type): 実行されるトランザクションの種類を指定する
- [phone_number_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-phone_number_collection): 顧客の電話番号を収集する
- [tax_id_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-tax_id_collection): 税務 ID を収集する

> #### サポートされていない CheckoutSession パラメータ
> 
> 組み込みフォームは、`allow_promotion_codes` や `consent_collection` をサポートしていません。

## Stripe Elements を設定する [クライアント側]

#### React

組み込みフォームは、Stripe.js の機能として利用できます。npm パブリックレジストリから [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) と [Stripe.js loader](https://www.npmjs.com/package/@stripe/stripe-js) をインストールします。

```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```

サーバーから返される client secret を含む `Promise<string> | string` として `clientSecret` を作成します。[CheckoutFormProvider](https://docs.stripe.com/js/react_stripe_js/checkout_form/checkout_form_provider) コンポーネントでアプリケーションをラップし、`clientSecret` と `stripe` インスタンスを渡します。

```jsx
import React, {useMemo} from 'react';
import {CheckoutFormProvider, CheckoutForm} from '@stripe/react-stripe-js/checkout';
import {loadStripe} from '@stripe/stripe-js';

const stripePromise = loadStripe(
  '<<YOUR_PUBLISHABLE_KEY>>',
  {betas: ['custom_checkout_payment_form_1']}
);

const App = () => {
  const clientSecret = useMemo(() => (
    fetch('/create-checkout-session', {method: 'POST'})
      .then((response) => response.json())
      .then((json) => json.client_secret)
  ), []);

  return (
    <CheckoutFormProvider
      stripe={stripePromise}
      options={{clientSecret}}
    >
      <CheckoutForm />
    </CheckoutFormProvider>
  );
};

export default App;
```

#### HTML + JS

埋め込みフォームは、Stripe.js の機能として自動的に利用できます。HTML ファイルの head に Stripe.js スクリプトを追加して、決済画面に含めます。PCI 準拠を維持するため、Stripe.js は必ず js.stripe.com から直接読み込んでください。スクリプトをバンドルに含めたり、そのコピーを自分でホストしたりしないでください。

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

決済画面で Stripe のインスタンスを作成します。

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>', {
  betas: ['custom_checkout_payment_form_1']
});
```

サーバーから Client Secret を取得し、Checkout フォーム SDK を初期化します。

```javascript
const clientSecret = fetch('/create-checkout-session', {method: 'POST'})
  .then((response) => response.json())
  .then((json) => json.client_secret);
```

Checkout フォーム SDK インスタンスを作成します。

```javascript
const checkout = stripe.initCheckoutFormSdk({
  clientSecret
});
```

## 作成とマウント [クライアント側]

埋め込みフォームには、HTTPS 接続を通じて決済情報を Stripe に安全に送信する iframe が含まれています。

#### React

`CheckoutForm` コンポーネントは、前のステップですでに `CheckoutFormProvider` 内にレンダリングされています。React に追加のマウントは必要ありません。

#### HTML + JS

組み込みフォームには、決済画面上に専用の場所を指定する必要があります。決済フォーム内に一意の ID を持つ空の DOM ノード (コンテナ) を作成します。

```html
<div id="checkout-form">
  <!-- embedded form will be inserted here -->
</div>
```

Checkout Form SDK インスタンスの準備ができたら、組み込みフォームを作成し、コンテナの DOM ノードにマウントします。

```javascript
const form = checkout.createForm();
form.mount('#checkout-form');
```

[layout](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-layout) を指定すると、組み込みフォームを単一ステップまたは複数ステップの組み込みフォームとしてレンダリングできます。

## 顧客のメールアドレスを事前入力する

メールを編集可能にするかどうかに応じて、2 つの方法のいずれかを使用して顧客のメールアドレスを事前入力できます。

### Checkout Session にメールを設定する (編集不可)

サーバーで Checkout Session を作成する際に、[customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) を渡します。このメールアドレスは組み込みフォームに表示されますが、顧客はこれを変更できません。また、[Customer](https://docs.stripe.com/api/customers.md) ID を [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) フィールドに渡すことで、Customer に保存されているメールアドレスを事前入力することもできます。

### クライアントでデフォルトのメールを設定する (編集可能)

編集可能なメールアドレスを事前入力するには、SDK の初期化時に `defaultValues.email` を渡します。顧客は、組み込みフォームでこの値を変更できます。

#### React

```jsx
<CheckoutFormProvider
  stripe={stripePromise}
  options={{
    clientSecret,
    defaultValues: {
      email: 'customer@example.com',
    },
  }}
>
  <CheckoutForm />
</CheckoutFormProvider>
```

#### HTML + JS

```javascript
const checkout = stripe.initCheckoutFormSdk({
  clientSecret,
  defaultValues: {
    email: 'customer@example.com',
  },
});
```

## 決済を確定する [クライアント側]

サーバーで作成した Checkout Session によって、明細項目、合計金額、利用可能な決済手段が自動的に決まります。埋め込みフォームはこの情報を使用して、適切なインターフェイスを表示します。

#### React

### 決済確定を処理する

顧客が決済を確定したときに confirm イベントを処理します。

```jsx
import React, {useMemo} from 'react';
import {CheckoutFormProvider, CheckoutForm, useCheckoutForm} from '@stripe/react-stripe-js/checkout';
import {loadStripe} from '@stripe/stripe-js';

const stripePromise = loadStripe(
  '<<YOUR_PUBLISHABLE_KEY>>',
  {betas: ['custom_checkout_payment_form_1']}
);

const CheckoutPage = () => {
  const checkoutState = useCheckoutForm();

  if (checkoutState.type === 'error') {
    return <div>Error: {checkoutState.error.message}</div>;
  }

  const onConfirm = (event) => {
    if (checkoutState.type === 'success') {
       checkoutState.checkout.confirm({formConfirmEvent: event});
    }
  };

  return <CheckoutForm onConfirm={onConfirm} />;
};

const App = () => {
  const clientSecret = useMemo(() => (
    fetch('/create-checkout-session', {method: 'POST'})
      .then((response) => response.json())
      .then((json) => json.client_secret)
  ), []);

  return (
    <CheckoutFormProvider
      stripe={stripePromise}
      options={{clientSecret}}
    >
      <CheckoutPage />
    </CheckoutFormProvider>
  );
};

export default App;
```

### エラーを処理する

埋め込みフォームは、クライアントによる確認中に、ローカライズされた顧客向けエラーメッセージを自動的に表示します。問題が発生して確定メソッドを続行できない場合、確定メソッドで例外が発生することがあります。これらの例外をキャッチして処理してください。

```jsx
const onConfirm = async (event) => {
  if (checkoutState.type === 'success') {
    try {
      await checkoutState.checkout.confirm({formConfirmEvent: event});
    } catch (error) {
      console.error('Payment confirmation error:', error);
    }
  }
};
```

#### HTML + JS

### 決済確定を処理する

顧客が決済を確定したときに confirm event をリッスンします。

```javascript
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  form.on('confirm', (event) => {
    loadActionsResult.actions.confirm({formConfirmEvent: event});
  });
}
```

埋め込みフォームは、クライアントによる確認中に、ローカライズされた顧客向けエラーメッセージを自動的に表示します。即時の問題によって確定メソッドを続行できない場合、確定メソッドで例外が発生することがあります。これらの例外をキャッチして処理してください。

```javascript
form.on('confirm', async (event) => {
  try {
    await checkout.confirm({formConfirmEvent: event});
  } catch (error) {
    console.error('Payment confirmation error:', error);
  }
});
```

> #### リダイレクトの動作のカスタマイズ
> 
> By default, after a successful payment, the embedded form redirects your customer to the `return_url` that you specify when you create the Checkout Session. To prevent redirects for payment methods that don’t require a redirect, such as cards, set [redirect](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) to `'if_required'` when calling [confirm](https://docs.stripe.com/js/custom_checkout/confirm). To learn more, see [Customize redirect behavior](https://docs.stripe.com/payments/checkout/custom-success-page.md?payment-ui=checkout-form).

## 決済後のイベントを処理 [サーバー側]

Checkout Session では、明細項目、配送オプション、その他の決済設定を定義します。顧客がクライアント側で決済を確定した後は、クライアント側の状態に依存せず、サーバーで結果を処理します。

- **Webhook** (Recommended): 決済が成功したときに Stripe が送信する [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) イベントをリッスンすれば、リダイレクト前に顧客がブラウザを閉じた場合でも通知を受け取れます。
- **Return page**: ID を使用して [Checkout Session](https://docs.stripe.com/api/checkout/sessions/retrieve.md) を取得すれば、決済ステータスを確認し、`return_url` として設定したページに顧客向けの適切な結果を表示できます。

決済を受け取った後に[注文を処理](https://docs.stripe.com/checkout/fulfillment.md?payment-ui=checkout-form)する方法をご紹介します。

## 組み込みをテストする

本番環境へ移行する前に、各決済手段の導入を[テスト](https://docs.stripe.com/testing.md)してください。**Pay** をクリックして決済を完了すると、指定したリターンページにリダイレクトされます。

リターンページが表示され、ダッシュボードの成功した決済のリストに決済が表示されていれば、実装は正常に動作しています。

#### カード

Stripe の[テストカード番号](https://docs.stripe.com/testing.md#cards)を使用してカード決済をテストします。例:

| Scenario                            | Card Number      |
| ----------------------------------- | ---------------- |
| Payment succeeds                    | 4242424242424242 |
| Payment requires 3DS authentication | 4000002500003155 |
| Payment is declined                 | 4000000000009995 |

#### ワンクリック決済ボタン

ワンクリック決済ボタンをテストするには、以下の手順に従ってください。

1. ブラウザーに決済手段を追加します。たとえば、カードを Google Pay アカウントや Safari のウォレットに追加できます。
2. アプリケーションを HTTPS 経由で提供してください。これは開発環境と本番環境の両方で必要です。[ngrok](https://ngrok.com/) などのサービスを使用できます。
3. *サンドボックス* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) と本番環境の両方で[ドメインを登録](https://dashboard.stripe.com/settings/payment_method_domains)します。
4. [Express Checkout Element テストガイド](https://docs.stripe.com/elements/express-checkout-element/accept-a-payment.md?payment-ui=embedded-components#test-integration)の手順に従ってください。

## レイアウトと外観をカスタマイズする

オプションを設定するか、Appearance API を使用して、組み込みフォームをカスタマイズできます。

### 組み込みフォームのオプション

組み込みフォーム全体のレイアウトを設定し、エクスプレス決済手段の各ボタンの外観のスタイルを設定するオプションを使用できます。

#### React

```jsx
const checkoutFormOptions = {
  layout: 'expanded',

  expressCheckout: {
    buttonTheme: {
      applePay: 'white-outline'
    },
    paymentMethods: {
      applePay: 'always'
    }
  }
};

<CheckoutForm
  options={checkoutFormOptions}
  onConfirm={onConfirm}
/>
```

#### HTML + JS

```javascript
const form = checkout.createForm({
  layout: 'expanded',

  expressCheckout: {
    buttonTheme: {
      applePay: 'white-outline'
    },
    paymentMethods: {
      applePay: 'always'
    }
  }
});

form.mount('#checkout-form');
```

組み込みフォームは以下のオプションをサポートしています。

|  |
|  |
| `layout`                         | 組み込みフォームのレイアウト。オプションには `expanded` と `compact` があります。これを未定義のままにすると、Stripe はコンバージョンが最も高いと判断したレイアウトをレンダリングします。                                                                             |
| `expressCheckout.buttonTheme`    | ワンクリック決済ボタンごとにテーマを指定します。[buttonTheme](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-expressCheckout-buttonTheme) を参照してください。                |
| `expressCheckout.paymentMethods` | どのワンクリック決済ボタンを表示するかを指定します。[paymentMethods](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-expressCheckout-paymentMethods) を参照してください。        |
| `contacts`                       | 保存された住所を表すオブジェクトの配列。それぞれに `name`、`address`、`phone` のプロパティーが含まれます。詳しくは[連絡先](https://docs.stripe.com/js/custom_checkout/create_form#custom_checkout_create_form-options-contacts)をご覧ください。 |

### Appearance API

[Appearance API](https://docs.stripe.com/elements/appearance-api.md) を使用すると、テーマを適用したり特定の詳細を更新したりして、組み込みフォームのスタイルを制御できます。ただし、組み込みフォームは `rules` オプションに対応していません。

たとえば、「flat」テーマを選択して、プライマリテキストの色を上書きします。

#### React

```jsx
const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};

<CheckoutFormProvider
  stripe={stripePromise}
  options={{
    clientSecret, // 実際の実装では、バックエンドが決済金額などの詳細を含むハッシュを渡します。詳細はサンプルコード全体をご覧ください。
    appearance
  }}
>
  <CheckoutForm />
</CheckoutFormProvider>
```

#### HTML + JS

```javascript
const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};

const checkout = stripe.initCheckoutFormSdk({
  clientSecret, // 実際の実装では、バックエンドが決済金額などの詳細を含むハッシュを渡します。詳細はサンプルコード全体をご覧ください。
  appearance
});
```

## 顧客に Stripe を開示する

Stripe は顧客の Elements とのやり取りに関する情報を収集して、サービスを提供し、不正利用を防止し、サービスを向上します。これには、Cookie と IP アドレスを使用して、1 つの決済フローセッションで顧客に表示する Elements を特定することが含まれます。Stripe がこのような方法でデータを使用するために必要なすべての権利と同意について開示し、これらを取得することはお客様の責任です。詳細については、[プライバシーセンター](https://stripe.com/legal/privacy-center#as-a-business-user-what-notice-do-i-provide-to-my-end-customers-about-stripe)をご覧ください。

## See also

- [顧客が決済に使用した決済手段を保存する](https://docs.stripe.com/payments/save-during-payment.md?payment-ui=embedded-components)