画面上の入力を収集する

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

Readers: Stripe Reader S700 and BBPOS WisePOS E

With Terminal smart readers, you can display input forms and collect information from your customers. You can choose from six input types and they can be used in a variety of use cases.

Collect your customer identifier for loyalty redemption with the phone or email input and process it on your backend.
Have your customer acknowledge a waiver or agreement with the signature input.
Ask your customer to fill out a questionnaire with the selection or text input.

You can display input forms anytime before payment, post payment and outside of a payment cycle.

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

注

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

入力を収集する

To collect inputs using Terminal’s smart readers, use the collect_inputs command. The API communicates with the reader to display a prebuilt UI.

カスタマイズ

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

Set important inputs as required to ensure they’re collected. For required inputs, the Skip button is hidden.
custom_text を使用して、リーダー画面で入力ごとに表示するテキストを指定し、顧客にコンテキストを提供します。

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

`description`	custom_text	500 when used with the `selection` form, 100 when used with other form type
`submit_button`	custom_text	300

`skip_button`	custom_text	14

Use line breaks \n in your text for better formatting.
顧客がブール値オプション、契約、またはオプトインを有効または無効にできる最大 4 つのトグルを追加します。

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

フィールド名	フィールドの場所	最大文字数
`title`	toggles	50, 25 when used with toggle description
`description`	toggles	50, 25 when used with toggle title

Additional customization is available for selection inputs. When specifying the choices, you can emphasize or de-emphasize choices using the style parameter.

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

メタデータ

You can include metadata, like a customer or order ID, in your request. The request payload includes the specified metadata, which appears in both the synchronous response and the success or failure events. By including a unique identifier, you can more easily identify and handle the incoming event.

顧客とのやり取り

When the reader begins collecting inputs, it displays the first input from the list. The customer must make a selection, provide a signature, or use the keyboard to proceed with required inputs. For optional inputs, the customer has the option to skip to the next requested input.

After the customer has completed all the inputs, the reader changes to a transitional state for 3 seconds, waiting for a subsequent request. If there is no subsequent request after 3 seconds, the reader changes back to the splash screen.

注

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

入力データを受信する

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

署名タイプの入力の場合、値は、署名の画像を SVG 形式で取得するファイルの ID です。
選択タイプの入力の場合、id と text は、選択した選択肢の id と text に対応します。
電話、メール、テキスト、数値の各インプットの値は、顧客のレスポンスの文字列になります。
顧客がオプションの入力をスキップした場合、skipped パラメーターが true に設定されます。
The value of each toggle is populated with enabled or 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"

Subscribe to events to receive collected inputs as soon as they’re available. Alternatively, you can retrieve the events from the reader as a backup if your backend fails to consume the event. Stripe sends two webhooks to notify your backend of the reader’s status:

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

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

To download the collected signature image, retrieve the file and use your secret key to access its url.

注

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

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

You can test your integration by using a simulated reader. After creating a simulated reader, start collecting inputs using the simulated reader.

The simulated reader supports simulating the following scenarios:

Successful input collection without skipping any inputs
Successful input collection with skipping all non-required inputs
Failed input collection because of a timeout

When simulating successful input collection, the simulated reader returns a hard-coded value for each input based on the type.