Best Practices für die Verwendung von QuellenVeraltet

Dank der Flexibilität der Sources-API können Sie den Änderungsaufwand im Zusammenhang mit der Unterstützung zusätzlicher Zahlungsmethoden minimieren.

Typischer Ablauf von Kartenzahlungen

In einem typischen Ablauf des Bezahlvorgangs für Kartenzahlungen (ohne 3D Secure) erfasst Ihre Integration die Kartendaten und erstellt eine Quelle, die dann für eine Zahlungsanforderung verwendet wird. Da die Kundin/der Kunde nichts weiter unternehmen muss und Kartenzahlungen synchron bestätigt werden, können wir direkt bestätigen, ob die Zahlung erfolgreich war und ob die Gelder garantiert werden können. Webhooks sind hierfür nicht erforderlich.

Wann Webhooks erforderlich sind

Andere Zahlungsmethoden setzen unter Umständen voraus, dass Ihre Kundin/Ihr Kunde zusätzliche Schritte unternimmt (beispielsweise eine Weiterleitung), damit eine Quelle chargeable wird und für eine Zahlungsanforderung (beispielsweise iDEAL) verwendet werden kann. Dieser Übergang geschieht in der Regel asynchron und kann auch noch erfolgen, nachdem die Kundin/der Kunde Ihre Website verlassen hat. Aus diesen Gründen benötigt Ihre Integration Webhooks, um zu bestimmen, wann eine Quelle abrechenbar wird, bevor Sie eine Zahlung erstellen.

Stripe übermittelt die folgenden Webhook-Ereignisse, um Sie über Änderungen am Status der Quelle zu informieren:

Ebenso kann es beim Erstellen einer Zahlung geschehen, dass bei bestimmten asynchronen Zahlungsmethoden einige Tage benötigt werden, bis die Gelder bestätigt sind und die Zahlung abgebucht ist. Durch den Einsatz von Webhooks wissen Sie genau, wann Sie Ihre Bestellungen bestätigen und abwickeln können.

Stripe übermittelt die folgenden Webhook-Ereignisse, um Sie über Änderungen am Status einer Zahlung zu informieren:

Aufbau einer flexiblen Integration

Um sicherzustellen, dass Ihr Bezahlvorgang flexibel ist und mehrere Zahlungsmethoden unterstützt, empfehlen wir die folgende Vorgehensweise:

Erstellung von Quellen

Erfassen Sie beim Erstellen von Quellen die Quell-ID in Ihrer internen Bestellübersicht, damit Sie die Bestellung zuordnen können, wenn Sie source.chargeable-Webhooks empfangen und verarbeiten. Indizieren Sie Ihre Bestellobjekte basierend auf diesem source-Attribut, um eine effiziente Abfrage zu ermöglichen.

Erstellung von Zahlungen

Durch die Übergabe des Webhooks source.chargeable wird die Quelle belastet. Wenn Sie den Webhook empfangen, rufen Sie Ihre interne Bestellübersicht auf, indem Sie mit der erhaltenen Quell-ID eine Abfrage durchführen, und verifizieren Sie, dass für die Bestellung eine Zahlung aussteht.

Wenn Sie eine Ladeanfrage stellen, verwenden Sie Ihre interne Auftrags-ID als Idempotenzschlüssel, um mögliche Racebedingung zu vermeiden. Wenn die Quelle wiederverwendbar ist und Sie sie wiederverwenden möchten, stellen Sie außerdem sicher, dass Sie sie vor dem Aufladen an eine/n Kundin/Kunden anschließen. In den Handbüchern Einweg oder wiederverwendbar und Quellen und Kundinnen/Kunden erfahren Sie mehr über den Umgang mit Einweg- und wiederverwendbaren Quellen und deren Interaktion mit Kundinnen/Kunden.

Erfassen Sie wie beim Erstellen von Quellen die Zahlungs-ID in Ihrer internen Bestellübersicht, damit Sie die Bestellung zuordnen können, wenn Sie charge.succeeded-Webhooks empfangen.

Bestätigungsseite

Nachdem Ihr/e Kund/in die erforderlichen Schritte zur Autorisierung einer Zahlung unternommen hat (beispielsweise einer Weiterleitung gefolgt ist), sollten Sie eine Bestätigungsseite anzeigen, aus der der Bestellstatus hervorgeht. Hierfür können Sie die Bestellung intern abfragen.

Da bei der Übertragung von Webhooks eine Latenz nicht gewährleistet ist, können Sie den Status der zugehörigen Source in Ihrem clientseitigen Code abfragen, um die Bestätigungsseite weiter zu optimieren. Wenn Sie feststellen, dass Ihre Source chargeable geworden ist, können Sie das Erstellen einer Charge mit dieser Source auslösen, ohne auf den Webhook source.chargeable warten zu müssen.

Beachten Sie, dass es bei einigen Arten von Quellen einige Minuten (oder sogar Tage) dauern kann, bis sie chargeable sind. Wenn Sie die Quelle manuell abfragen, empfehlen wir, den Prozess zu unterbrechen und den/die Kund/in darüber in Kenntnis zu setzen, dass für die Bestellung eine Zahlungsbestätigung aussteht. Anschließend können Sie asynchron per E-Mail eine Zahlungsbestätigung versenden. In der folgenden Tabelle finden Sie unsere Meldungen, die Kund/innen je nach Quellstatus angezeigt werden.

Clientseitige Abfragen werden unterbrochen, wenn der/die Kund/in Ihre Seite verlässt. Daher müssen Sie auch den Webhook source.chargeable bei der Integration berücksichtigen, um die Kundenbestellung nicht aus den Augen zu verlieren.

Wenn Sie Stripe.js verwenden, können Sie mithilfe von stripe.retrieveSource() Ihre eigene Abfrage implementieren:

// In order-confirmation-page.js

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// After some amount of time, we should stop trying to resolve the order synchronously:
const MAX_POLL_COUNT = 10;
let pollCount = 0;

const pollForSourceStatus = async () => {
  const {source} = await stripe.retrieveSource({id: SOURCE_ID, client_secret: CLIENT_SECRET})
  if (source.status === 'chargeable') {
    // Make a request to your server to charge the Source.
    // Depending on the Charge status, show your customer the relevant message.
  } else if (source.status === 'pending' && pollCount < MAX_POLL_COUNT) {
    // Try again in a second, if the Source is still `pending`:
    pollCount += 1;
    setTimeout(pollForSourceStatus, 1000);
  } else {
    // Depending on the Source status, show your customer the relevant message.
  }
};

pollForSourceStatus();

Die folgende Tabelle zeigt Vorschläge für mögliche Meldungen, die Kund/innen je nach Status der Quelle angezeigt werden können.

Wenn Sie eine Zahlung erstellt haben (und der/die Kund/in noch auf Ihrer Bestätigungsseite verweilt), können Sie je nach Status der Zahlung die folgenden Meldungen anzeigen:

Bestellbestätigung

Sie sollten eine Bestellung erst bestätigen, nachdem Sie den Webhook charge.succeeded erhalten haben (das kann direkt der Fall sein, muss aber nicht). Halten Sie den/die Kund/in in diesem Schritt per E-Mail auf dem Laufenden, da die Zahlungsbestätigung bei asynchronen Zahlungen ein paar Tage dauern kann.

Stornierungen und fehlgeschlagene Zahlungen

Warten Sie auf die Webhooks source.canceled und source.failed und stornieren Sie dann die zur jeweiligen Quelle gehörende Bestellung. Wenn Sie die oben erwähnten Best Practices befolgen, sollten Sie bei Quellen, die bereits chargeable waren, keinen Webhook source.canceled empfangen (da Ihr source.chargeable-Handler sofort eine Zahlung erstellt und damit verhindert haben sollte, dass die Quelle storniert wird). Für Quellen, die nie chargeable waren, sondern immer den Status pending hatten, empfangen Sie allerdings weiterhin den Webhook source.canceled. Dazu kommt es beispielsweise, wenn ein/e Kund/in Ihren Bezahlvorgang vorzeitig verlässt. Den Webhook source.failed empfangen Sie immer dann, wenn ein/e Kund/in die Zahlung verweigert oder auf Ebene des Zahlungsschemas ein technischer Fehler auftritt.

Darüber hinaus sollten Sie auf den Webhook charge.failed warten, um sicherzustellen, dass Sie die zur erhaltenen Zahlung gehörende Bestellung stornieren.

Bei jedem dieser Ereignisse empfehlen wir, den/die Kund/in über die fehlgeschlagene Bestellung zu informieren und, falls gewünscht, die Wiederaufnahme des Bezahlvorgangs anzubieten.