Kartenzahlungen einziehen

Für die Lesegeräte BBPOS WisePOS E und Stripe Reader S700 empfehlen wir eine serverseitige Integration, da sie die Stripe API anstelle eines Terminal-SDK verwendet, um Zahlungen einzuziehen.

Zum Einziehen von Zahlungen mit Stripe Terminal müssen Sie einen Zahlungsablauf in Ihrer Anwendung programmieren. Verwenden Sie das Stripe Terminal SDK, um einen PaymentIntent zu erstellen und zu aktualisieren. Bei einem PaymentIntent handelt es sich um ein Objekt, das eine einzelne Zahlungssitzung darstellt.

Während die Kernkonzepte SDK-basierten Integrationen ähneln, sehen die Schritte bei der servergesteuerten Integration etwas anders aus:

1. PaymentIntent erstellen Sie können definieren, ob Ihre Zahlungen automatisch oder manuell erfasst werden sollen.
2. Zahlung verarbeiten Die Autorisierung der Kundenkarte erfolgt, wenn das Lesegerät die Zahlung verarbeitet.
3. (Optional) PaymentIntent erfassen.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d currency=usd \
  -d "payment_method_types[]"=card_present \
  -d capture_method=manual \
  -d amount=1000

curl https://api.stripe.com/v1/terminal/readers/tmr_xxx/process_payment_intent \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=pi_xxx

curl https://api.stripe.com/v1/terminal/readers/tmr_xxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

{
  "id": "tmr_xxx",
  "object": "terminal.reader",
  ...
  "status": "online",
  "action": {
    "type": "process_payment_intent",
    "process_payment_intent": {
      "payment_intent": "pi_xxx"
    },
    "status": "in_progress",
    "failure_code": null,
    "failure_message": null
  }
}

curl -X POST https://api.stripe.com/v1/payment_intents/pi_xxx/capture \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Status des Lesegeräts verifizieren

Um sicherzustellen, dass das Lesegerät eine Aktion abgeschlossen hat, muss Ihre Anwendung den Status des Geräts überprüfen, bevor Sie eine neue Lesegeräte-Aktion veranlassen oder mit der Erfassung fortfahren können. In den meisten Fällen können Sie mit dieser Verifizierung eine erfolgreiche (genehmigte) Zahlung bestätigen und Ihrem Betreiber jede relevante Nutzererfahrung anzeigen, damit er die Transaktion abschließen kann. In anderen Fällen müssen Sie möglicherweise Fehler beheben, wie zum Beispiel abgelehnte Zahlungen.

Verwenden Sie eine der folgenden Methoden, um den Status des Lesegeräts zu überprüfen:

• Webhooks überwachen
• Stripe API abfragen
• PaymentIntent verwenden
• Lesegerät-Objekt verwenden

Webhooks überwachen Empfohlen

Für maximale Ausfallsicherheit empfehlen wir, dass Ihre Anwendung Webhooks von Stripe überwacht, um in Echtzeit Benachrichtigungen über den Status des Lesegeräts zu erhalten. Stripe sendet drei Webhooks, um Ihre Anwendung über den Aktionsstatus eines Lesegeräts zu informieren:

Um diese Webhooks zu überwachen, erstellen Sie einen Webhook-Endpoint. Wir empfehlen, einen speziellen Webhook-Endpoint nur für diese Ereignisse einzurichten, da sie hohe Priorität haben und sich im kritischen Zahlungspfad befinden.

curl https://api.stripe.com/v1/webhook_endpoints \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "enabled_events[]"="terminal.reader.action_succeeded" \
  -d "enabled_events[]"="terminal.reader.action_failed" \
  --data-urlencode url="https://example.com/my/webhook/endpoint"

Die Stripe-API abfragen

Bei Problemen mit der Webhook-Zustellung können Sie die Stripe-API abfragen, indem Sie Ihrer Point-of-Sale-Schnittstelle die Schaltfläche check status hinzufügen, die der Bediener bei Bedarf aufrufen kann.

PaymentIntent verwenden

Sie können den PaymentIntent abrufen, den Sie zur Verarbeitung an das Lesegerät übergeben haben. Wenn Sie einen PaymentIntent erstellen, befindet dieser sich zunächst im Status requires_payment_method. Nachdem Sie die Zahlungsmethode erfolgreich erfasst haben, wird der Status auf requires_confirmation aktualisiert. Nachdem die Zahlung erfolgreich verarbeitet wurde, wird der Status auf requires_capture aktualisiert.

curl https://api.stripe.com/v1/payment_intents/
{{PAYMENT_INTENT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Das Lesegerät-Objekt verwenden

Sie können das Lesegeräte-Objekt verwenden, das ein Aktions-Attribut enthält, das die letzte vom Lesegerät empfangene Aktion und ihren Status anzeigt. Ihre Anwendung kann ein Lesegerät abrufen, um zu prüfen, ob sich der Status der Lesegerät-Aktion geändert hat.

curl https://api.stripe.com/v1/terminal/readers/tmr_xxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Das Reader-Objekt wird ebenfalls als Antwort auf den Zahlungsvorgangsschritt zurückgegeben. Der action-Typ beim Verarbeiten einer Zahlung ist process_payment_intent.

Der action.status wird bei erfolgreicher Zahlung auf succeeded aktualisiert. Das bedeutet, Sie können mit dem Abschluss der Transaktion fortfahren. Andere mögliche Werte für action.status sind failed oder in_progress.

Umgang mit Fehlern

Die folgenden Fehler sind die häufigsten Typen, die Ihre Anwendung verarbeiten muss:

• Doppelte Abbuchungen vermeiden
• Fehlgeschlagene Zahlungen
• Zeitüberschreitung der Zahlung
• Stornierung der Zahlung
• Lesegerät bereits in Nutzung
• Zeitüberschreitung des Lesegeräts
• Lesegerät offline
• Fehlende Webhooks
• Verzögerte Webhooks

Doppelte Abbuchungen vermeiden

Das PaymentIntent-Objekt ermöglicht Geldbewegungen bei Stripe – verwenden Sie einen einzigen PaymentIntent, um eine Transaktion darzustellen.

Verwenden Sie denselben PaymentIntent, nachdem eine Karte abgelehnt wurde (z. B. wenn sie nicht ausreichend gedeckt ist), damit Ihre Kundin/Ihr Kunde es mit einer anderen Karte erneut versuchen kann.

Wenn Sie den PaymentIntent bearbeiten, müssen Sie process_payment_intent aufrufen, um die Zahlungsinformationen auf dem Lesegerät zu aktualisieren.

Ein PaymentIntent muss sich im Status requires_payment_method befinden, bevor Stripe ihn verarbeiten kann. Ein autorisierter, erfasster oder stornierter PaymentIntent kann nicht von einem Lesegerät verarbeitet werden und resultiert im Fehler intent_invalid_state:

curl https://api.stripe.com/v1/terminal/readers/tmr_xxx/process_payment_intent \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=pi_xxx

{
  "error": {
    "code": "intent_invalid_state",
    "doc_url": "https://docs.stripe.com/error-codes#intent-invalid-state",
    "message": "Payment intent must be in the requires_payment_method state to be processed by a reader.",
    "type": "invalid_request_error"
  }
}

Fehlgeschlagene Zahlungen

Zu den häufigsten Zahlungsfehlern gehört eine fehlgeschlagene Zahlung. (Zum Beispiel, wenn eine Zahlung von der Bank des/der Kund/in aufgrund unzureichender Deckung abgelehnt wird).

Wenn die Autorisierung einer Zahlung fehlschlägt, sendet Stripe den Webhook terminal.reader.action_failed. Überprüfen Sie die Attribute action.failure_code und action.failure_message, um herauszufinden, ob eine Zahlung abgelehnt wurde:

{
  "id": "tmr_xxx",
  "object": "terminal.reader",
  "action": {
    "failure_code": "card_declined",
    "failure_message": "Your card has insufficient funds.",
    "process_payment_intent": {
      "payment_intent": "pi_xxx"
    },
    "status": "failed",
    "type": "process_payment_intent"
  },
  ...
}

Fordern Sie Kundinnen/Kunden im Falle einer abgelehnten Karte auf, eine alternative Zahlungsmethode anzugeben. Verwenden Sie denselben PaymentIntent in einer anderen Anfrage an den Endpoint process_payment_intent. Wenn Sie einen neuen PaymentIntent erstellen, müssen Sie den fehlgeschlagenen PaymentIntent stornieren, um doppelte Zahlungen zu vermeiden.

Bei Kartenlesefehlern (z. B. Fehler beim Lesen des Chips) fordert das Lesegerät Kundinnen/Kunden automatisch zu einem Wiederholungsversuch auf, ohne dass Ihre Anwendung benachrichtigt wird. Wenn mehrere Wiederholungsversuche fehlschlagen, können Sie durch Stellen einer weiteren process_payment_intent-Anfrage eine andere Zahlungsmethode anfordern.

Zeitüberschreitung bei der Zahlung

Ein Lesegerät mit unzuverlässiger Internetverbindung kann aufgrund einer Netzwerkanfrage bei der Autorisierung der Karte eine Zahlung nicht verarbeiten. Das Lesegerät zeigt einige Sekunden lang einen Verarbeitungsbildschirm an, gefolgt von einer Fehlermeldung, und Sie erhalten terminal.reader.action_failed-Webhook mit dem failure_code connection_error:

{
  "id": "tmr_xxx",
  "object": "terminal.reader",
  "action": {
    "failure_code": "connection_error",
    "failure_message": "Could not connect to Stripe.",
    "process_payment_intent": {
      "payment_intent": "pi_xxx"
    },
    "status": "failed",
    "type": "process_payment_intent"
  },
  ...
}

Die Zahlungsbestätigungsanfrage wurde möglicherweise von den Backend-Systemen von Stripe verarbeitet, aber das Lesegerät hat die Verbindung möglicherweise getrennt, bevor es die Antwort von Stripe erhalten hat. Wenn Sie einen Webhook mit diesem Fehlercode erhalten, rufen Sie den PaymentIntent-status ab, um zu überprüfen, ob die Zahlung erfolgreich autorisiert wurde.

Stellen Sie sicher, dass Ihr Netzwerk unsere Netzwerkanforderungen erfüllt, um Zeitüberschreitungen zu vermeiden.

Stornierung der Zahlung

Programmgesteuerte Stornierung

Möglicherweise müssen Sie eine Zahlung, die bereits unterwegs ist, stornieren. Beispielsweise wenn Kundinnen/Kunden Artikel zu ihrem Kauf hinzufügen, nachdem Ihre Integration die Erfassung der Zahlung auf dem Lesegerät bereits eingeleitet hat. Verwenden Sie den Endpoint cancel_action, um das Lesegerät zurückzusetzen:

curl -X POST https://api.stripe.com/v1/terminal/readers/tmr_xxx/cancel_action \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Kundenseitig initiierte Stornierung

Nutzer/innen können den Wert von enable_customer_cancellation auf diesen Endpoints festlegen:

• process_payment_intent
• process_setup_intent
• collect_payment_method
• refund_payment

curl https://api.stripe.com/v1/terminal/readers/tmr_xxx/process_payment_intent \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=pi_xxx \
  -d "process_config[enable_customer_cancellation]"=true

Wenn „true“, sehen Nutzer/innen intelligenter Kartenlesegeräte eine Schaltfläche zum Stornieren.

Zahlungseinzug mit aktivierter Stornierung

Durch Tippen auf die Schaltfläche „Abbrechen“ wird die aktive Transaktion abgebrochen. Stripe sendet einen Webhook terminal.reader.action_failed mit dem failure_code customer_canceled.

{
  "action": {
    "failure_code": "customer_canceled",
    "failure_message": "This action could not be completed due to an error on the card reader.",
    "process_payment_intent": {
      "payment_intent": "pi_xxx",
      "process_config": {
        "enable_customer_cancellation": true
      }
    },
    "status": "failed",
    "type": "process_payment_intent"
  }
}

Lesegerät beschäftigt

Ein Lesegerät kann jeweils nur eine Zahlung verarbeiten. Während eine Zahlung verarbeitet wird, schlägt der Versuch einer neuen Zahlung mit einem terminal_reader_busy-Fehler fehl:

curl https://api.stripe.com/v1/terminal/readers/tmr_xxx/process_payment_intent \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=pi_xxx

{
  "error": {
    "code": "terminal_reader_busy",
    "doc_url": "https://docs.stripe.com/error-codes#terminal-reader-timeout",
    "message": "Reader is currently busy processing another request. Please reference the integration guide at https://stripe.com/docs/terminal/payments/collect-card-payment?terminal-sdk-platform=server-driven#handle-errors for details on how to handle this error.",
    "type": "invalid_request_error"
  }
}

Zahlungen, deren Bearbeitung noch nicht begonnen hat, können durch neue ersetzt werden.

Ein Lesegerät lehnt eine API-Anfrage auch ab, wenn es Aktualisierungen durchführt oder Einstellungen ändert.

Timeout des Lesegeräts

In seltenen Fällen kann es vorkommen, dass ein Lesegerät aufgrund von temporären Netzwerkproblemen nicht rechtzeitig auf eine API-Anfrage reagiert. In diesem Fall erhalten Sie den Fehlercode terminal_reader_timeout:

curl https://api.stripe.com/v1/terminal/readers/tmr_xxx/process_payment_intent \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=pi_xxx

{
  "error": {
    "code": "terminal_reader_timeout",
    "doc_url": "https://docs.stripe.com/error-codes#terminal-reader-timeout",
    "message": "There was a timeout when sending this command to the reader. Please reference the integration guide at https://stripe.com/docs/terminal/payments/collect-card-payment?terminal-sdk-platform=server-driven#handle-errors for details on how to handle this error.",
    "type": "invalid_request_error"
  }
}

In diesem Fall empfehlen wir Ihnen, die API-Anfrage erneut durchzuführen. Stellen Sie sicher, dass Ihr Netzwerk unsere Netzwerkanforderungen erfüllt, um Zeitüberschreitungen zu vermeiden.

In seltenen Fällen ist der Fehlercode terminal_reader_timeout falsch negativ. In diesem Szenario erhalten Sie, wie oben beschrieben, den Fehler terminal_reader_timeout von der API, das Lesegerät hat den Befehl jedoch empfangen. Falsch negative Ergebnisse treten auf, wenn Stripe eine Nachricht an das Lesegerät sendet, aber aufgrund vorübergehender Netzwerkfehler keine Bestätigung vom Lesegerät erhält.

Lesegerät offline

Wenn an einem Standort die Internetverbindung unterbrochen wird, kann dies zu einer Unterbrechung der Kommunikation zwischen dem Lesegerät und Stripe führen. In diesem Fall reagieren ein Lesegeräte möglicherweise nicht auf Ereignisse, die von Ihrer Point-of-Sale-Anwendung und Backend-Infrastruktur ausgelöst werden.

Ein Lesegerät, das regelmäßig nicht auf API-Anfragen reagiert, ist höchstwahrscheinlich ausgeschaltet (z. B. das Netzkabel ist nicht angeschlossen oder der Akku leer) oder nicht korrekt mit dem Internet verbunden.

Ein Lesegerät gilt als offline, wenn Stripe in den letzten 2 Minuten kein Signal von diesem Lesegerät erhalten hat. Der Versuch, API-Methoden auf einem Offline-Lesegerät aufzurufen, führt zu einem terminal_reader_offline-Fehlercode:

{
  "error": {
    "code": "terminal_reader_offline",
    "doc_url": "https://docs.stripe.com/error-codes#terminal-reader-offline",
    "message": "Reader is currently offline, please ensure the reader is powered on and connected to the internet before retrying your request. Reference the integration guide at https://stripe.com/docs/terminal/payments/collect-card-payment?terminal-sdk-platform=server-driven#handle-errors for details on how to handle this error.",
    "type": "invalid_request_error"
  }
}

Halten Sie sich an unsere Netzwerkanforderungen, um sicherzustellen, dass ein Lesegerät korrekt mit dem Internet verbunden ist.

Fehlende Webhooks

Wenn ein Lesegerät während einer Zahlung die Verbindung trennt, kann es seinen Aktionsstatus in der API nicht aktualisieren. In diesem Szenario zeigt das Lesegerät nach dem Vorzeigen einer Karte einen Fehlerbildschirm an. Das Lesegerät-Objekt in der API wird jedoch nicht so aktualisiert, dass der Fehler auf dem Gerät widergespiegelt wird, und Sie erhalten auch keine Webhooks für die Lesegerätaktion. Ein Lesegerät kann in diesem Fall den Aktionsstatus in_progress haben. Kassierer/innen müssen dann eingreifen, indem sie den Endpoint cancel_action zum Zurücksetzen des Lesegerätstatus aufrufen.

Verzögerte Webhooks

In seltenen Fällen kann es bei einem Stripe-Ausfall zu Verzögerungen bei den Webhooks für Lesegerätaktionen kommen. Sie können den Status der Reader- oder PaymentIntent-Objekte abfragen, um den aktuellen Status zu ermitteln.

Webhook-Ereignisse