Collect InputsBeta
Use Terminal to collect inputs from your customers.
Available in: All supported countries for Stripe S700 and BBPOS WisePOS E using server-driven integration and client Terminal SDKs.
Note
This feature was previously called On-Reader Forms. To request access to the Collect Inputs beta for server-driven or client Terminal SDKs, email us.
Collect inputs![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
In addition to collecting payments, Terminal smart readers allow you to display forms and collect information from customers. You make requests to the Stripe API, and the API communicates with the reader to display a prebuilt UI to collect customer input. Stripe notifies your backend of the customer’s responses using webhooks.
To collect inputs using Terminal’s smart readers, use the collect_inputs command. You can specify up to 5 inputs at a time, and the reader collects them in sequence. Stripe smart readers currently support six input types:
- The
selection
input type allows you to display up to 4 choices for a customer to select from. - The
signature
input type allows you to collect a signature using the reader’s touchscreen. - The
email
input type allows you to collect an email address from a customer. - The
phone
input type allows you to collect a phone number from a customer. - The
text
input type allows you to collect additional information from customers. - The
numeric
input type allows you to collect additional information from customers.
![Supported input types.](https://b.stripecdn.com/docs-statics-srv/assets/collect-inputs-form-types.9715c2bbc0105378c9c4a5e8e1c4eb59.png)
Supported input types.
You can customize the appearance and behavior of all input types:
- Set important inputs as required to make sure they’re collected. For required inputs, the skip button is hidden.
- Provide context to your customer by specifying the text you want to display on the reader screen for each input using custom_text.
- Add up to 4 toggles that customers can enable or disable for Boolean options, agreements, or opt-ins.
Field name | Field location | Maximum characters |
title | 40 | |
description | 350 | |
when used with the selection form | ||
description | 100 | |
when used with any other form type | ||
submit_ | 30 | |
skip_ | 14 | |
title | 50 | |
description | 50 | |
![Toggles in email and selection form](https://b.stripecdn.com/docs-statics-srv/assets/collect-inputs-toggle.3183c0c14cc916374d588ba54ad34639.png)
Email and selection form with toggle
Additional customization is available for selection inputs. When specifying the choices you want to display to the customer, you can emphasize or de-emphasize choices using the style parameter.
![Selection choice styles](https://b.stripecdn.com/docs-statics-srv/assets/collect-inputs-choice-style.dc4d2fcb98ee649a29bc43df806c114a.png)
Primary and secondary selection choice styles
In addition to the list of inputs, you might want to include metadata in your request. The request payload includes the specified metadata, which appears in both the synchronous response and the success or failure webhooks. By including a unique identifier such as a customer ID or order ID, you can more easily identify and handle the incoming webhook.
Beta
You must include the terminal_
header to use the collect_
preview feature. The reader object won’t include the collect_inputs object in API responses if you omit the header.
Note
Don’t use collect_
to collect sensitive data (including protected health information and customer payment card information), or any information restricted by law.
Customer interaction![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
When the reader begins collecting inputs, it displays the first input from the list you specified to the customer. The customer must make a selection, provide a signature, or use the keyboard to proceed with required inputs. However, for optional inputs, the customer has the option to skip to the next requested input.
After the customer has either submitted or skipped all inputs, Stripe updates the reader object and sends out the terminal.
webhook. The reader transitions to an interstitial state for 3 seconds, where it’s able to navigate to a subsequent request. After the 3 seconds, the reader transitions back to the splash screen.
Note
You are fully responsible for being aware of, and complying with all applicable laws and regulations governing your use of this feature, and must in relation to such use, obtain, as applicable, all necessary consents, authorizations, licenses, rights, and permissions. If you use input collected by, or output displayed from a Terminal smart reader to enter into contracts with, or provide notices to your customers, you are fully responsible for ensuring the legal validity and enforceability of such contracts or notices.
Receive input data![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Use the curl command below as an example to create a webhook endpoint to receive the collected inputs.
curl https://api.stripe.com/v1/webhook_endpoints \ -u
: \ --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"sk_test_4eC39HqLyjWDarjtT1zdp7dc
Caution
You must create the webhook endpoint directly with Stripe’s /v1/webhook_endpoints API. The collect_inputs object doesn’t return complete results if you create the webhook endpoint with Stripe CLI or Stripe server-side SDKs. To make sure that the collect_
object is present in the webhook payload, include terminal_
in the request header and set the api_
property when you create the webhook endpoint.
You won’t be able to update an existing webhook to start listening to collected inputs, you must create a new one.
When all inputs have been collected or skipped, Stripe sends a request to your webhook endpoint. The request payload is identical to the response when calling collect_inputs, but adds a few additional parameters:
- The
value
parameter is populated for each collected input. - If an optional input is skipped by the customer, the skipped parameter is set to
true
. - The
value
of each toggle is populated withenabled
ordisabled
.
Subscribe to webhooks to receive collected inputs as soon as they’re available. You can retrieve the reader with the terminal_
request header as a backup if your backend fails to consume the webhook.
Stripe sends two webhooks to notify your backend of the reader’s status:
terminal.
: Sent when areader. action_ succeeded collect_
action succeeds.inputs terminal.
: Sent when areader. action_ failed collect_
action fails. This includes timeouts, which occur after the reader screen isn’t touched for 2 minutes.inputs
Download signature images![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To receive the collected signature image, retrieve the file and use your secret key to access its URL.
Note
Stripe stores the signature images you collect for 7 days. If you need to use signature images more than 7 days after collecting them, download the file and store it. You are fully responsible for being aware of and complying with all laws that apply to your use, storage, and disclosure of your customers’ signatures.
Beta SDK![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
If you use one of Stripe’s server-side SDKs, you must install a beta version. For installation instructions, refer to the relevant GitHub page for the server SDK you want to use.
You also need to configure your SDK’s API version to include the beta header mentioned above. View language-specific examples of how to accomplish this.