画面上の入力を収集する

Terminal を使用して、顧客から入力を収集します。

リーダー: Stripe Reader S700 および BBPOS WisePOS E

Terminal スマートリーダーを使用すると、入力フォームを表示して、顧客から情報を収集できます。6 つの入力タイプから選択でき、さまざまなユースケースで利用できます。

phone または email 入力でロイヤルティ引き換えのための顧客識別子を収集し、バックエンドで処理します。
signature 入力で権利放棄と同意を顧客に認めてもらいます。
selection または text 入力で、アンケートへの回答を顧客に依頼します。

入力フォームは、支払い前、支払い後、支払いサイクル外のいつでも表示することができます。

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

注

collect_inputs を使用して、機密データ (保護された健康情報や顧客の決済カード情報など)、または法律によって制限されている情報を収集することはできません。

入力を収集する

Terminal のスマートリーダーを使用して入力を収集するには、collect_inputs コマンドを使用します。API はリーダーと通信して、構築済みの UI を表示します。

カスタマイズ

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

重要な入力が確実に収集されるように、必須として設定します。必須入力の場合、スキップボタンは非表示になります。
custom_text を使用して、リーダー画面で入力ごとに表示するテキストを指定し、顧客にコンテキストを提供します。

フィールド名	フィールドの場所	最大文字数
`title`	custom_text	40

`description`	custom_text	`selection` フォームで使用する場合は 500、他のタイプのフォームで使用する場合は 100
`submit_button`	custom_text	300

`skip_button`	custom_text	14

テキストに改行を加えて、書式を改善します。
顧客がブール値オプション、契約、またはオプトインを有効または無効にできる最大 4 つのトグルを追加します。

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

フィールド名	フィールドの場所	最大文字数
`title`	toggles	50、説明のトグル使用時は 25
`description`	toggles	50、タイトルのトグル使用時は 25

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

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

メタデータ

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

顧客とのやり取り

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

顧客がすべての入力を完了すると、リーダーは 3 秒間にわたって移行状態に変わり、後続のリクエストを待ちます。3 秒経過しても後続のリクエストがなかった場合、リーダーはスプラッシュ画面に戻ります。

注

お客様は、この機能の使用に対して適用され、該当する法律と規制のすべてを理解してこれに準拠する責任をすべて負うものとされ、その使用に関連して、規定に従い、必要なすべての同意、承認、ライセンス、権利および許可を取得する必要があります。Terminal スマートリーダ－によって収集される入力、またはスマートリーダーから表示される出力を使用して顧客と契約を結ぶ場合、または顧客に通知を提供する場合、その契約または通知の法的な妥当性と法的強制力を確保することは、お客様の責任になります。

入力データを受信する

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

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

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

Command Line
curl https://api.stripe.com/v1/webhook_endpoints \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  --header "Stripe-Version: 2025-05-28.basil;" \
  --data-urlencode "url"="https://example.com/webhook/endpoint" \
  --data-urlencode "api_version"="2025-05-28.basil;" \
  --data-urlencode "enabled_events[]"="terminal.reader.action_succeeded" \
  --data-urlencode "enabled_events[]"="terminal.reader.action_failed"

イベントに登録し、利用可能になり次第、収集済みの入力を受信します。また、バックエンドでイベントを使用できない場合、バックアップとしてリーダーからイベントを取得することもできます。Stripe は、2 つの Webhook を送信して、リーダーのステータスをバックエンドに通知します。

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

署名の画像をダウンロードする

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

注

Stripe は、収集した署名の画像を 7 日間保存します。署名イメージを収集してから 7 日以上後に使用する必要がある場合は、ファイルをダウンロードして保存してください。顧客の署名の使用、保管、開示に適用されるすべての法律を理解して準拠することは、お客様の責任になります。

構築したシステムをテストする

シミュレーションされたリーダーを使用して、実装をテストできます。シミュレーションされたリーダーを作成したら、そのリーダーを使用して入力情報の収集を開始します。

シミュレーションされたリーダーは、以下のシナリオのシミュレーションに対応しています。

入力をスキップすることなく入力情報の収集に成功
不要な入力をすべてスキップして入力情報の収集に成功
タイムアウトのため、入力情報の収集に失敗

入力情報の収集の成功をシミュレーションする場合、シミュレーションされたリーダーはタイプに基づいて各入力にハードコード化された値を返します。