配送オプションを動的にカスタマイズする

顧客の配送先住所に基づいて配送オプションを更新します。

ページをコピー

Learn how to dynamically update shipping options based on the address that your customer enters in Checkout.

Use cases

Validate an address: Confirm whether you can ship a product to a customer’s address using your own custom validation rules. You can also create a custom UI for customers to confirm their preferred address.
Show relevant shipping options: Display only available shipping methods, based on the customer’s address. For example, show overnight shipping only for deliveries in your country.
Dynamically calculate shipping rates: Calculate and display shipping fees based on a customer’s delivery address.
Update shipping rates based on order total: Offer shipping rates based on the shipping address or order total, such as free shipping for orders over 100 USD. For checkouts allowing quantity changes or cross-sells, see Dynamically updating line items.

Limitations

Only supported in payment mode. Shipping rates aren’t available in subscription mode.
Doesn’t support updates in response to changes from outside of the checkout page.

Checkout セッションを作成する
サーバー側

サーバーで Checkout セッションを作成します。

ui_mode を embedded に設定します。
Set the permissions.update_shipping_details to server_only.
shipping_address_collection.allowed_countries に、配送先を提供する国のリストを設定します。
shipping_options.shipping_rate_data を設定して、0 USD のダミー配送料を作成します。

デフォルトでは、Stripe Checkout クライアントは、Checkout セッションオブジェクトの shipping_details を、顧客が入力する顧客の名前や住所などの配送情報で自動的に更新します。

警告

When permissions.update_shipping_details is server_only, it disables the automatic client-side update and only your server can update the shipping details using your Stripe secret key.

配送オプションをカスタマイズする
サーバー側

サーバーで、顧客の配送先住所に基づいて配送オプションを計算する新しいエンドポイントを作成します。

リクエスト本文から取得した checkoutSessionId を使用して、Checkout セッションを取得します。
リクエスト本文にある顧客の配送先情報を検証します。
顧客の配送先住所と Checkout セッションのラインアイテムに基づいて配送オプションを計算します。
顧客の shipping_details と shipping_options で Checkout セッションを更新します。

Ruby
require 'sinatra'
require 'json'
require 'stripe'

set :port, 4242

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"


# Return a boolean indicating whether the shipping details are valid
def validate_shipping_details(shipping_details)
  # TODO: Remove error and implement...
  raise NotImplementedError.new(<<~MSG)
    Validate the shipping details the customer has entered.
  MSG
end

# Return an array of the updated shipping options or the original options if no update is needed
def calculate_shipping_options(shipping_details, session)
  # TODO: Remove error and implement...
  raise NotImplementedError.new(<<~MSG)
    Calculate shipping options based on the customer's shipping details and the
    Checkout Session's line items.
  MSG
end

post '/calculate-shipping-options' do
  content_type :json
  request.body.rewind
  request_data = JSON.parse(request.body.read)

  checkout_session_id = request_data['checkout_session_id']
  shipping_details = request_data['shipping_details']

  # 1. Retrieve the Checkout Session
  session = Stripe::Checkout::Session.retrieve(checkout_session_id)

  # 2. Validate the shipping details
  if !validate_shipping_details(shipping_details)
    return { type: 'error', message: "We cannot ship to your address. Please choose a different address." }.to_json
  end

  # 3. Calculate the shipping options
  shipping_options = calculate_shipping_options(shipping_details, session)

  # 4. Update the Checkout Session with the customer's shipping details and shipping options
  if shipping_options
    Stripe::Checkout::Session.update(checkout_session_id, {
      collected_information: { shipping_details: shipping_details },
      shipping_options: shipping_options
    })

    return { type: 'object', value: { succeeded: true } }.to_json
  else
    return { type: 'error', message: "We can't find shipping options. Please try again." }.to_json
  end
end

Checkout をマウントする
クライアント側

Checkout は Stripe.js の一部として利用できます。HTML ファイルのヘッダーに Stripe.js スクリプトを追加してページに含めます。次に、マウンティングに使用する空の DOM ノード (コンテナ) を作成します。

index.html
<head>
  <script src="https://js.stripe.com/v3/"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

公開可能な API キーで Stripe.js を初期化します。

index.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

サーバーに Checkout セッションの作成をリクエストする非同期の fetchClientSecret 関数を作成し、クライアントシークレットを取得します。

顧客の配送先住所に基づいて配送オプションを計算するようにサーバーへリクエストする、非同期の onShippingDetailsChange 関数を作成します。顧客が配送先情報フォームの入力を終えると、Stripe Checkout がこの関数を呼び出します。

index.js
initialize();

async function initialize() {
  // Fetch Checkout Session and retrieve the client secret
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Call your backend to set shipping options
  const onShippingDetailsChange = async (shippingDetailsChangeEvent) => {
    const {checkoutSessionId, shippingDetails} = shippingDetailsChangeEvent;
    const response = await fetch("/calculate-shipping-options", {
      method: "POST",
      body: JSON.stringify({
        checkout_session_id: checkoutSessionId,
        shipping_details: shippingDetails,
      })
    })

    if (response.type === 'error') {
      return Promise.resolve({type: "reject", errorMessage: response.message});
    } else {
      return Promise.resolve({type: "accept"});
    }
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
    onShippingDetailsChange,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

注意

onShippingDetailsChange 関数からは必ず Promise が返され、ResultAction オブジェクトで解決されます。

Checkout クライアントは、onShippingDetailsChange 関数の結果に基づいて UI を更新します。

結果に type: "accept" が含まれる場合、Checkout UI はサーバーで設定した配送オプションを表示します。
結果に type: "reject" が含まれる場合、Checkout UI は結果で設定したエラーメッセージを表示します。

必要に応じて、onShippingDetailsChange をリッスンし、複数の可能な住所から希望の住所を選択して確認するための、カスタム UI を作成できます。

Checkout は、HTTPS 接続を介して支払い情報をStripeに安全に送信する iframe でレンダリングされます。

よくある間違い

一部の支払い方法では、別のページにリダイレクトして支払いを確定する必要があるため、Checkout は別の iframe 内に配置しないでください。

実装をテストする

Follow these steps to test your integration, and ensure your custom shipping options work correctly.

Set up a sandbox environment that mirrors your production setup. Use your Stripe sandbox API keys for this environment.
Simulate various shipping addresses to verify that your calculateShippingOptions function handles different scenarios correctly.
Verify server-side logic by using logging or debugging tools to confirm that your server:
- Retrieves the Checkout Session.
- Validates shipping details.
- Calculates shipping options.
- Updates the Checkout Session with new shipping details and options. Make sure the update response contains the new shipping details and options.
Verify client-side logic by completing the checkout process multiple times in your browser. Pay attention to how the UI updates after entering shipping details. Make sure that:
- The onShippingDetailsChange function is called when expected.
- Shipping options update correctly based on the provided address.
- Error messages display properly when shipping is unavailable.
Enter invalid shipping addresses or simulate server errors to test error handling, both server-side and client-side.

注