Collect on-screen inputsBeta

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.

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.

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.

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.

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

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.reader.action_succeeded 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.

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 
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"

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.
  • For signature type inputs, the value is a file ID that retrieves the signature image as an SVG.
  • For selection type inputs, the value is the string of the selected choice’s value.
  • For phone, email, text, and numeric inputs, the value is the string of the customer’s response.
• If an optional input is skipped by the customer, the skipped parameter is set to true.
• The value of each toggle is populated with enabled or disabled.

Subscribe to webhooks to receive collected inputs as soon as they’re available. You can retrieve the reader with the terminal_collect_inputs_beta=v1 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.reader.action_succeeded: Sent when a collect_inputs action succeeds.
• terminal.reader.action_failed: Sent when a collect_inputs action fails. This includes timeouts, which occur after the reader screen isn’t touched for 2 minutes.

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