Eingaben auf dem Bildschirm erfassen

Um Eingaben mit den intelligenten Lesegeräten von Terminal zu erfassen, verwenden Sie den Befehl collect_inputs. Die API kommuniziert mit dem Lesegerät, um eine vorgefertigte Nutzeroberfläche anzuzeigen.

curl https://api.stripe.com/v1/terminal/readers/
{{READER_ID}}
/collect_inputs \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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][text]"=Email \
  -d "inputs[1][selection][choices][0][id]"=email_id \
  -d "inputs[1][selection][choices][1][style]"=primary \
  -d "inputs[1][selection][choices][1][text]"=Printed \
  -d "inputs[1][selection][choices][1][id]"=printed_id \
  -d "inputs[1][selection][choices][2][style]"=secondary \
  -d "inputs[1][selection][choices][2][text]"="No thanks" \
  -d "inputs[1][selection][choices][2][id]"=no_thanks_id \
  -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

Anpassung

Sie können das Erscheinungsbild und das Verhalten aller Eingabetypen anpassen:

• Legen Sie wichtige Eingaben nach Bedarf fest, um sicherzustellen, dass sie erfasst werden. Bei Pflichteingaben ist die Schaltfläche Überspringen ausgeblendet.
• Stellen Sie Ihren Kundinnen/Kunden Kontext zur Verfügung, indem Sie mit custom_text angeben, welcher Text für jede Eingabe auf dem Lesegerät angezeigt werden soll.

• Verwenden Sie Zeilenumbrüche in Ihrem Text für eine bessere Formatierung.
• Fügen Sie bis zu 4 Umschalter hinzu, die Kundinnen/Kunden für boolesche Optionen, Vereinbarungen oder Anmeldungen (Opt-Ins) aktivieren oder deaktivieren können.

E-Mail und Auswahlformular mit Umschalter

• Für Auswahl-Eingaben sind zusätzliche Anpassungen verfügbar. Beim Festlegen der Auswahlmöglichkeiten können Sie die Auswahl mithilfe des Design-Parameters hervorheben oder abschwächen.

Primäre und sekundäre Auswahlstile für Designs

Metadaten

Sie können Metadaten, wie eine Kunden- oder Bestell-ID, in Ihre Anfrage aufnehmen. Die Anforderungsnutzdaten enthalten die angegebenen Metadaten, die sowohl in der synchronen Antwort als auch in den Erfolgs- oder Fehlerereignissen angezeigt werden. Durch Einfügen einer eindeutigen Kennung können Sie das eingehende Ereignis leichter identifizieren und verarbeiten.

Wenn das Lesegerät mit der Erfassung von Eingaben beginnt, zeigt es die erste Eingabe aus der Liste an. Der Kunde/die Kundin muss eine Auswahl treffen, unterschreiben oder die Tastatur verwenden, um mit den erforderlichen Eingaben fortzufahren. Bei optionalen Eingaben hat der Kunde/die Kundin die Möglichkeit, zur nächsten angeforderten Eingabe zu springen.

Nachdem der Kunde/die Kundin alle Eingaben abgeschlossen hat, wechselt das Lesegerät für 3 Sekunden in einen Übergangszustand und wartet auf eine nachfolgende Anfrage. Wenn nach 3 Sekunden keine weitere Anfrage erfolgt, wechselt das Lesegerät wieder zum Begrüßungsbildschirm.

Wenn alle Eingaben erfasst oder übersprungen wurden, sendet Stripe eine Anfrage an Ihren Webhook-Endpoint. Die Anfragenutzlast ist identisch mit der Antwort beim Aufruf von collect_inputs, verfügt jedoch über ein paar zusätzliche Parameter:

• Bei Eingaben vom Typ „Signatur“ ist der Wert eine Datei-ID, die das Signaturbild als SVG abruft.
• Bei Eingaben vom Typ „Auswahl“ entsprechen die ID and Text der id und dem text der ausgewählten Auswahl.
• Bei Telefon-, E-Mail-, Text- und numerischen Eingaben ist der Wert die Zeichenfolge der Kundenantwort.
• Wenn eine optionale Eingabe von der Kundin/dem Kunden übersprungen wird, wird der Übersprungen-Parameter auf true gesetzt.
• Der Wert jedes Umschalters wird mit enabled oder disabled ausgefüllt.

Verwenden Sie den folgenden curl-Befehl als Beispiel, um einen Webhook-Endpunkt zu erstellen, um die gesammelten Eingaben zu empfangen.

curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_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"

Abonnieren Sie Ereignisse, um erfasste Informationen zu erhalten, sobald diese verfügbar sind. Alternativ können Sie die Ereignisse als Backup vom Lesegerät abrufen, wenn Ihr Backend das Ereignis nicht verarbeiten kann. Stripe sendet zwei Webhooks, um Ihr Backend über den Status des Lesegeräts zu informieren:

• terminal.reader.action_succeeded: Wird gesendet, wenn eine collect_inputs-Aktion erfolgreich ist.
• terminal.reader.action_failed: Wird gesendet, wenn eine collect_inputs-Aktion fehlschlägt. Dies schließt Zeitüberschreitungen ein, die auftreten, nachdem das Lesegerät 2 Minuten lang nicht berührt wurde.

Um das erfasste Signaturbild herunterzuladen, rufen Sie die Datei ab und verwenden Sie Ihren Geheimschlüssel, um auf die zugehörige URL zuzugreifen.