画面上の入力を収集するベータ

Terminal スマートリーダーでは、支払いを回収する以外にフォームを表示して、顧客から情報を収集することができます。Stripe API に対してリクエストを行うと、API はリーダーと通信して、事前構築された UI を表示し、顧客の入力を収集します。バックエンドには、Webhook を使用して、顧客のレスポンスが通知されます。

Terminal のスマートリーダーを使用して入力を収集するには、collect_inputs コマンドを使用します。一度に最大 5 件の入力を指定でき、リーダーはそれらを順番に収集します。Stripe のスマートリーダーは現在、以下の 6 つの入力タイプをサポートしています。

• selection 入力タイプでは、顧客に提示する選択項目を最大 4 つまで表示できます。
• signature 入力タイプでは、リーダーのタッチスクリーンを使用して署名を収集することができます。
• email 入力タイプでは、顧客からメールアドレスを収集できます。
• phone 入力タイプでは、顧客から電話番号を収集できます。
• text 入力タイプでは、顧客から追加情報を収集できます。
• numeric 入力タイプでは、顧客から追加情報を収集できます。

対応している入力タイプ。

すべての入力タイプでデザインと動作をカスタマイズすることができます。

• 重要な入力が確実に収集されるように、必須として設定します。必須の入力では、スキップボタンは非表示になります。
• custom_text を使用して、リーダー画面で入力ごとに表示するテキストを指定し、顧客にコンテキストを提供します。
• 顧客がブール値オプション、契約、またはオプトインを有効または無効にできる最大 4 つの トグル を追加します。

メールと選択フォームの切り替え

選択入力の場合、さらにカスタマイズすることができます。顧客に表示する選択項目を指定する際に style パラメーターを使用して、選択項目の強調や強調解除ができます。

1 次および 2 次の選択項目のスタイル

リクエストには、入力のリストのほかにメタデータを含めることができます。リクエストペイロードには指定されたメタデータが含まれ、同期レスポンスと、成功または失敗の Webhook の両方に表示されます。顧客 ID や注文 ID などの一意の ID を含めることで、受信する Webhook の特定や処理を簡単にすることができます。

curl https://api.stripe.com/v1/terminal/readers/
{{READER_ID}}
/collect_inputs \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Version: 2024-11-20.acacia; terminal_collect_inputs_beta=v1;" \
  -d "inputs[0][type]"=signature \
  -d "inputs[0][custom_text][title]"="Rental Agreement" \
  -d "inputs[0][custom_text][description]"="Please sign below to indicate that you agree to the rental agreement." \
  -d "inputs[0][custom_text][submit_button]"=Submit \
  -d "inputs[0][required]"=true \
  -d "inputs[1][type]"=selection \
  -d "inputs[1][selection][choices][0][style]"=primary \
  -d "inputs[1][selection][choices][0][value]"=Email \
  -d "inputs[1][selection][choices][1][style]"=primary \
  -d "inputs[1][selection][choices][1][value]"=Printed \
  -d "inputs[1][selection][choices][2][style]"=secondary \
  -d "inputs[1][selection][choices][2][value]"="No thanks" \
  -d "inputs[1][custom_text][title]"=Receipt \
  --data-urlencode "inputs[1][custom_text][description]"="How would you like your receipt?" \
  -d "inputs[1][required]"=true \
  -d "inputs[2][type]"=email \
  -d "inputs[2][custom_text][title]"="Enter your email" \
  --data-urlencode "inputs[2][custom_text][description]"="We'll send updates on your order and occasional deals" \
  -d "inputs[2][required]"=true \
  -d "inputs[2][toggles][0][title]"="Opt-in for marketing emails" \
  -d "inputs[2][toggles][0][default_value]"=enabled \
  -d "metadata[order_number]"=12345

リーダーが入力の収集を開始すると、顧客には、指定したリストの最初の入力が表示されます。次に進むには、顧客は選択または署名を行うか、キーボードを使用して必須項目を入力する必要があります。入力がオプションである場合、顧客は次の入力リクエストにスキップすることができます。

顧客が入力の送信またはスキップを完了すると、リーダーオブジェクトは更新され、terminal.reader.action_succeeded Webhook が送信されます。リーダーは 3 秒間インタースティシャル状態に移行し、次のリクエストに移動できるようになります。3 秒後、リーダーはスプラッシュスクリーンに戻ります。

以下の curl コマンドを例として使用して、収集した入力項目を受信する Webhook エンドポイントを作成します。

curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  --header "Stripe-Version: 2023-10-16; terminal_collect_inputs_beta=v1" \
  --data-urlencode "url"="https://example.com/webhook/endpoint" \
  --data-urlencode "api_version"="2023-10-16;terminal_collect_inputs_beta=v1" \
  --data-urlencode "enabled_events[]"="terminal.reader.action_succeeded" \
  --data-urlencode "enabled_events[]"="terminal.reader.action_failed"

入力の収集またはスキップが完了すると、Stripe は、リクエストを Webhook エンドポイントに送信します。リクエストペイロードは、collect_inputs を呼び出す場合のレスポンスと同じですが、いくつかのパラメーターが追加されています。

• value パラメーターには、収集された各入力が設定されます。
  • 署名タイプの入力の場合、値は、署名の画像を SVG 形式で取得するファイルの ID です。
  • 選択タイプの入力の場合、値は、選択された項目の value の文字列です。
  • 電話、メール、テキスト、数値の各インプットの値は、顧客のレスポンスの文字列になります。
• 顧客がオプションの入力をスキップした場合、skipped パラメーターが true に設定されます。
• 各トグルの value には、enabled または disabled が入力されます。

収集された入力が利用可能になり次第、その入力を受信するには、Webhook に登録します。バックエンドで Webhook を使用できない場合、バックアップとして terminal_collect_inputs_beta=v1 リクエストヘッダーを使用してリーダーを取得できます。

Stripe は、2 つの Webhook を送信して、リーダーのステータスをバックエンドに通知します。

• terminal.reader.action_succeeded: collect_inputs アクションが成功したときに送信されます。
• terminal.reader.action_failed: collect_inputs アクションが失敗したときに送信されます。これには、リーダー画面が 2 分間タッチされないと発生するタイムアウトが含まれます。

収集された署名の画像を受信するには、ファイルを取得し、シークレットキーを使用して URL にアクセスします。