ACH Direct Debit mit der Charges APIVeraltet

Mit Stripe können Sie ACH-Zahlungen beinahe auf die gleiche Weise annehmen wie Kreditkartenzahlungen. Hierfür müssen Sie lediglich ein verifiziertes Bankkonto als source-Argument für eine Zahlungsanfrage angeben. Die Annahme von Zahlungen über Bankkonten erfordert jedoch zu Beginn einen etwas anderen Arbeitsablauf als die Annahme über Kreditkarten:

1. Sie müssen Bankkonten zunächst verifizieren.
2. Ihr/e Kund/in muss Sie für die Verwendung autorisieren.

Nachdem Ihre Kund/innen beide Schritte für ein Bankkonto durchgeführt haben, können sie es wie andere Zahlungsmethoden verwenden. Dies gilt auch für wiederkehrende Zahlungen und Connect-Anwendungen. Die beiden wichtigsten Unterschiede zwischen der Verwendung von Bankkonten und Kreditkarten sind die Folgenden:

• Bei ACH-Zahlungen dauert es bis zu fünf Werktage, bis Sie eine Bestätigung über die erfolgreiche oder fehlgeschlagene Zahlung erhalten. Daher dauert es bis zu sieben Werktage, bis ACH-Zahlungen in Ihrem verfügbaren Stripe-Saldo berücksichtigt werden.
• Sie können ausschließlich Gelder in USD und nur von Bankkonten in den USA annehmen. Zusätzlich muss Ihr Konto über ein US-Bankkonto (USD) verfügen, um ACH-Zahlungen annehmen zu können.

Bankkonten erfassen und verifizieren

Bevor Sie eine ACH-Zahlung erstellen können, müssen Sie zunächst das Bankkonto und die Routingnummer Ihres Kunden/Ihrer Kundin erfassen. Zur ordnungsgemäßen Identifizierung des Bankkontos müssen Sie außerdem den Namen der Person oder des Unternehmens erfassen, der/die Inhaber/in des Kontos ist. Ermitteln Sie außerdem, ob das Konto einer Einzelperson oder einem Unternehmen gehört. Stripe stellt dafür zwei Methoden zur Verfügung: die sofortige Erfassung und Verifizierung mittels Plaid oder die Erfassung über Stripe.js mit verzögerter Verifizierung mittels Mikroeinzahlungen. Je nach Größe Ihres Unternehmens können bei Verwendung von Plaid zusätzliche Kosten anfallen. Dies sollten Sie bei Ihrer Entscheidung berücksichtigen.

Da die Belastung eines Bankkontos sowohl die Verifizierung des Kontos als auch die Autorisierung der Kund/innen erfordert, ist es sinnvoll, das Bankkonto zur einfachen Wiederverwendung in einem Customer-Objekt in Stripe zu speichern.

Plaid verwenden

Plaid bietet die schnellste Möglichkeit, die Bankdaten Ihrer Kund/innen zu erfassen und zu verifizieren. Mit der Integration von Stripe und Plaid erhalten Sie unmittelbar ein verifiziertes Bankkonto, das Sie direkt belasten können. Hierzu wird Plaid Link verwendet, wobei Sie das Token für das Stripe-Bankkonto direkt von Plaid erhalten.

Schritt 1: Plaid-Konto einrichten

Wenn Sie noch kein Plaid-Konto haben, erstellen Sie eines. Ihr Konto wird automatisch für den Zugang zur Integration aktiviert. Um zu überprüfen, ob Ihr Plaid-Konto für die Stripe-Integration aktiviert ist, wechseln Sie zum Abschnitt Integrationen des Dashboards in Ihrem Konto. Stellen Sie sicher, dass Ihr Stripe-Konto dort verbunden ist.

Schritt 2: Link-Token abrufen

Ein link_token ist ein Token zur einmaligen Verwendung, das zur Initialisierung von Plaid Link verwendet wird. Sie können ein link_token erstellen und für Ihren spezifischen Link-Ablauf konfigurieren, indem Sie den Endpoint Link-Token erstellen von Ihrem Server aus abrufen.

curl https://sandbox.plaid.com/link/token/create \
  -H "Content-Type: application/json" \
  -d "{\"client_id\": \"{{PLAID_CLIENT_ID}}\",\"secret\": \"{{PLAID_SECRET}}\",\"client_name\": \"My App\",\"user\": {\"client_user_id\": \"Stripe test\"},\"products\": [\"auth\"],\"country_codes\": [\"US\"],\"language\": \"en\", \"webhook\": \"https://webhook.sample.com/\"}"

Schritt 3: Mit Plaid Link integrieren

Die Integration mit Link ist einfach. Es sind nur ein paar Zeilen clientseitiges JavaScript und ein kleiner serverseitiger Handler erforderlich, um den Link public_token gegen ein access_token für Plaid und ein Token für ein Stripe-Bankkonto auszutauschen.

<button id="link-button">Link Account</button>

<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script type="text/javascript">
(async function() {

  const configs = {
    // Pass the link_token generated in step 2.
    token: '{{LINK_TOKEN}}',
    onLoad: function() {
      // The Link module finished loading.
    },
    onSuccess: function(public_token, metadata) {
      // The onSuccess function is called when the user has
      // successfully authenticated and selected an account to
      // use.
      //
      // When called, you will send the public_token
      // and the selected account ID, metadata.accounts,
      // to your backend app server.
      //
      // sendDataToBackendServer({
      //   public_token: public_token,
      //   account_id: metadata.accounts[0].id
      // });
      console.log('Public Token: ' + public_token);
      switch (metadata.accounts.length) {
        case 0:
          // Select Account is disabled: https://dashboard.plaid.com/link/account-select
          break;
        case 1:
          console.log('Customer-selected account ID: ' + metadata.accounts[0].id);
          break;
        default:
          // Multiple Accounts is enabled: https://dashboard.plaid.com/link/account-select
      }
    },
    onExit: async function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
          // The user encountered a Plaid API error
          // prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent
      // API request IDs.
      // Storing this information can be helpful for support.
    },
  };

  var linkHandler = Plaid.create(configs);

  document.getElementById('link-button').onclick = function() {
    linkHandler.open();
  };
})();
</script>

Schritt 4: Serverseitigen Handler erstellen

Das Link-Modul wickelt den gesamten Onboarding-Ablauf sicher und schnell ab, ruft aber keine Kontodaten für eine/n Nutzer/in ab. Stattdessen gibt das Link-Modul über den onSuccess-Callback ein public_token und ein accounts-Array zurück, das eine Eigenschaft des metadata-Objekts ist.

Das accounts-Array enthält Informationen über Bankkonten, die den von dem/der Nutzer/in eingegebenen Anmeldedaten zugeordnet sind. Es kann mehrere Konten enthalten, wenn der/die Nutzer/in über mehrere Bankkonten bei dem Finanzinstitut verfügt. Um Verwirrung darüber zu vermeiden, welches Konto Ihr/e Nutzer/in mit Stripe verwenden möchte, wählen Sie im Entwickler-Dashboard von Plaid unter Select Account (Konto auswählen) die Option Enabled for one account (Für ein Konto aktiviert) aus. Wenn Sie diese Einstellung auswählen, enthält das Konten-Array immer genau ein Element.

Wenn Ihr Server über das public_token und die account_id verfügt, müssen Sie zwei Aufrufe des Plaid-Servers durchführen, um das Bankkonto-Token für Stripe zusammen mit dem access_token für Plaid zu erhalten, welches Sie für andere Plaid-API-Anfragen verwenden können.

curl https://sandbox.plaid.com/item/public_token/exchange \
  -H "Content-Type: application/json" \
  -d "{\"client_id\": \"{{PLAID_CLIENT_ID}}\", \"secret\": \"{{PLAID_SECRET}}\", \"public_token\": \"{{PLAID_LINK_PUBLIC_TOKEN}}\"}"

curl https://sandbox.plaid.com/processor/stripe/bank_account_token/create \
  -H "Content-Type: application/json" \
  -d "{\"client_id\": \"{{PLAID_CLIENT_ID}}\", \"secret\": \"{{PLAID_SECRET}}\", \"access_token\": \"{{PLAID_ACCESS_TOKEN}}\", \"account_id\": \"{{PLAID_ACCOUNT_ID}}\"}"

Die Antwort enthält eine verifizierte Stripe-Bankkonto-Token-ID. Dieses Token können Sie einem Customer-Objekt in Stripe hinzufügen oder direkt in diesem eine Zahlung erstellen.

{
  "stripe_bank_account_token": "btok_eGMHjytWOC8FZgJhAzve",
  "request_id": "[Unique request ID]"
}

Schritt 5: Vorbereitung auf die Produktionsumgebung

Plaid nutzt verschiedene API-Hosts für Test- und Produktionsanfragen. Bei der obigen Anfrage wird die Sandbox-Umgebung von Plaid mit simulierten Daten verwendet. Für Tests mit Live-Nutzer/innen können Sie die Entwicklungsumgebung von Plaid verwenden. Die Entwicklungsumgebung von Plaid unterstützt bis zu 100 Live-Objekte, die Ihnen nicht in Rechnung gestellt werden. Für das Go-Live verwenden Sie die Produktionsumgebung von Plaid.

Bankkonten manuell erfassen und verifizieren

Plaid unterstützt die sofortige Verifizierung für viele der gängigsten Banken. Wenn die Bank Ihres/Ihrer Kund/in jedoch nicht von Plaid unterstützt wird oder Sie keine Vernetzung mit Plaid wünschen, können Sie die Bank des/der Kund/in ausschließlich mit Stripe erfassen und verifizieren.

Verwenden Sie zunächst Stripe.js, um die Bankkontodaten Ihrer Kundinnen/Kunden sicher zu erfassen, und im Gegenzug ein repräsentatives Token zu erhalten. Wenn Sie dieses Token erhalten haben, fügen Sie es einem/einer Stripe-Kunden/Kundin in Ihrem Konto hinzu. Um die Nacha-Regeln zu erfüllen, müssen Sie unbedingt einen gültigen Kontoinhabernamen für den Kunden/die Kundin angeben.

curl https://api.stripe.com/v1/customers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "name"="Jenny Rosen" \
  -d "source"="btok_4XNshPRgmDRCVi"

Die Bankkonten von Kund/innen müssen verifiziert werden. Wenn Sie Stripe ohne Plaid nutzen, sendet Stripe zu diesem Zweck automatisch zwei kleine Einzahlungen. Es dauert 1 bis 2 Werktage, bis diese Einzahlungen auf dem Online-Kontoauszug des Kunden/der Kundin erscheinen. Die Abrechnung enthält die Beschreibung ACCTVERIFY. Ihr Kunde/Ihre Kundin muss diese Beträge an Sie weiterleiten.

Beachten Sie bei der Übernahme dieser Werte unbedingt, dass es eine Grenze von drei fehlgeschlagenen Verifizierungsversuchen gibt. Wenn Sie diese Grenze überschreiten, können wir das Bankkonto nicht verifizieren. Informieren Sie Ihre Kund/innen genau, worum es sich bei diesen Mikroeinzahlungen handelt und wie sie verwendet werden. So helfen Sie Ihren Kund/innen, Probleme bei der Verifizierung zu vermeiden. Sobald Ihnen diese Werte zur Verfügung stehen, können Sie das Bankkonto verifizieren:

curl https://api.stripe.com/v1/customers/cus_AFGbOSiITuJVDs/sources/ba_17SHwa2eZvKYlo2CUx7nphbZ/verify \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amounts[]"=32 \
  -d "amounts[]"=45

Sobald das Bankkonto verifiziert ist, können Sie damit Zahlungen vornehmen.

Zahlungsautorisierung

Holen Sie vor der Erstellung einer ACH-Zahlung die Genehmigung Ihrer Kund/innen ein, ihr Konto belasten zu dürfen. So können Sie die Konformität mit dem ACH-Netzwerk sicherstellen und sich vor Zahlungsanfechtungen, zusätzlichen Gebühren und Rückbuchungen schützen. Weitere Informationen zu den Autorisierungsanforderungen finden Sie auf der Support-Seite.

ACH-Zahlung erstellen

Um eine Abbuchung für ein verifiziertes Bankkonto zu erstellen, verwenden Sie das gespeicherte Customer-Objekt auf die gleiche Weise wie bei Verwendung einer Karte.

curl https://api.stripe.com/v1/charges \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1500 \
  -d currency=usd \
  -d customer=cus_AFGbOSiITuJVDs

Beim Versuch, ein nicht verifiziertes Bankkonto zu belasten, wird eine Fehlermeldung mit folgendem Wortlaut ausgegeben: „The customer’s bank account must be verified in order to create an ACH payment“ (Bankkonten von Kund/innen müssen verifiziert werden, damit eine ACH-Zahlung erstellt werden kann).

Wenn der Kunde/die Kundin über mehrere gespeicherte Quellen (eines beliebigen Typs) verfügt, geben Sie das zu verwendende Bankkonto an, indem Sie seine ID als source-Parameter übergeben.

Diese Integration testen

Sie können erfolgreiche und fehlgeschlagene ACH-Zahlungen mit den folgenden Bankleitzahlen und Kontonummern imitieren:

• Bankleitzahl: 110000000
• Kontonummer:
  • 000123456789 (erfolgreich)
  • 000111111116 (Fehler bei Verwendung)
  • 000111111113(Konto geschlossen)
  • 000222222227 (NSF/keine ausreichende Deckung)
  • 000333333335 (Abbuchung nicht autorisiert)
  • 000444444440 (ungültige Währung)

Um erfolgreiche und fehlgeschlagene Bankkontoverifizierungen zu imitieren, verwenden Sie die folgenden aussagekräftigen Beträge:

• [32, 45] (erfolgreich)
• [any other number combinations] (fehlgeschlagen)

Ablauf von ACH-Zahlungen

Bei ACH-Zahlungen kann es bis zu fünf Werktage dauern, bis eine Mitteilung über den Erfolg oder das Fehlschlagen einer Zahlung eingeht:

• Nachdem ACH-Zahlungen erstellt wurden, haben sie den Anfangsstatus pending.
• Eine _ausstehende_Saldo-Transaktion wird sofort erstellt. Sie gibt den Zahlungsbetrag abzüglich unserer Gebühr an.
• Zahlungen, die um oder nach 22:00 UTC erstellt wurden, werden zurzeit am nächsten Werktag bearbeitet.
• Innerhalb der folgenden vier Werktage ändert sich der Status der Zahlung je nach Bank des/der Kund/in in succeeded oder failed.
• Erfolgreiche ACH-Zahlungen werden nach sieben Werktagen in Ihrem verfügbaren Stripe-Guthaben angezeigt. Zu diesem Zeitpunkt können die Gelder automatisch oder manuell auf Ihr Bankkonto überwiesen werden.
• Bei fehlgeschlagenen ACH-Zahlungen wird die erstellte ausstehende Saldo-Transaktion umgekehrt.
• Ihren Kund/innen wird die Zahlung 1–2 Tage nach Erstellung der Abbuchung auf ihrem Kontoauszug angezeigt. (Ihre Kund/innen wissen, dass die Zahlung erfolgreich war, bevor die Bank Stripe benachrichtigt.)

Fehler können verschiedene Ursachen haben, z. B. keine ausreichende Deckung, eine falsche Kontonummer oder weil der Kunde/die Kundin Abbuchungen von seinem/ihrem Bankkonto deaktiviert hat.

In seltenen Fällen erhält Stripe möglicherweise einen ACH-Fehler von der Bank, nachdem eine Zahlung in den Status succeeded gewechselt ist. Stripe erstellt dann eine Zahlungsanfechtung mit folgendem reason:

• insufficient_funds
• incorrect_account_details
• bank_cannot_process

Stripe erhebt in diesem Fall eine Fehlergebühr.

Umgang mit angefochtenen Zahlungen in dieser Integration

Zahlungsanfechtungen bei ACH-Zahlungen unterscheiden sich grundlegend von denen bei Kreditkartenzahlungen. Wenn die Kundenbank die Anfrage zur Rückbuchung der Gelder für eine angefochtene Zahlung akzeptiert, zieht Stripe die Gelder sofort von Ihrem Stripe-Konto ab. Im Gegensatz zu Zahlungsanfechtungen bei Kreditkartenzahlungen können Sie Stornierungen von ACH-Lastschriften nicht anfechten. Sie müssen sich an Ihre Kundin/Ihren Kunden wenden, um die Situation zu klären.

Kundinnen/Kunden fechten eine ACH-Lastschriftzahlung über ihre Bank in der Regel bis zu 60 Kalendertage nach einer Abbuchung auf einem Privatkonto oder bis zu 2 Werktage bei einem Geschäftskonto an. In seltenen Fällen kann eine Lastschriftzahlung außerhalb dieser Fristen erfolgreich angefochten werden.

Risiko von doppelten Gutschriften bei ACH-Rückerstattungen und Zahlungsanfechtungen

Wenn Sie Ihren Kund/innen proaktiv eine Zahlung zurückerstatten, während deren Bank ihrerseits eine Zahlungsanfechtung einleitet, erhält der Kunde/die Kundin unter Umständen zwei Gutschriften für dieselbe Transaktion.

Wenn Sie eine Rückerstattung für eine ACH-Zahlung ausstellen, müssen Sie Ihre/n Kund/in sofort darüber informieren, dass Sie die Rückerstattung ausstellen und dass es 2–5 Werktage dauern kann, bis die Gelder auf seinem/ihrem Bankkonto angezeigt werden.

Rückerstattungen

Sie können ACH-Zahlungen bis zu 90 Tage nach dem Datum der ursprünglichen Zahlung mit dem Refund-Endpoint zurückerstatten. Der zeitliche Ablauf und die Risiken bei ACH-Rückerstattungen unterscheiden sich jedoch von denen bei Kartenrückerstattungen. Wenn eine Rückerstattung für eine ACH-Zahlung erfolgreich ist, sendet Stripe keine Benachrichtigung. Schlägt eine Rückerstattung für eine ACH-Zahlung jedoch fehl, erhalten Sie die Benachrichtigung refund.failed. Dies bedeutet, dass wir die Rückerstattung nicht verarbeiten konnten. Sie müssen die Gelder dann außerhalb von Stripe an Ihre Kundinnen/Kunden zurückerstatten. Dieser seltene Fall tritt in der Regel ein, wenn ein Konto zwischen der ursprünglichen Zahlung und der Rückerstattungsanfrage gesperrt wurde.

ACH-spezifische Webhook-Benachrichtigungen

Wenn Sie ACH nutzen, erhalten Sie zahlreiche der standardmäßigen Webhook-Benachrichtungen für Zahlungen, wobei es ein paar beachtenswerte Unterschiede gibt:

• Nachdem Sie die Abbuchung erstellt haben, erhalten Sie die Benachrichtigung charge.pending. Die Benachrichtigung charge.succeeded oder charge.failed erhalten Sie erst bis zu fünf Werktage später.
• Sie erhalten die Benachrichtigung charge.succeeded, nachdem der Status der Abbuchung zu succeeded gewechselt hat und die Gelder in Ihrem Saldo verfügbar sind.
• Sie erhalten die Benachrichtigung charge.failed, wenn die ACH-Überweisung aus einem beliebigen Grund fehlgeschlagen ist. Der Code failure_code und die Nachricht failure_message werden festgelegt und die Gelder werden zu diesem Zeitpunkt vom Ihrem ausstehenden Stripe-Saldo zurückgebucht.
• Sie erhalten die Benachrichtigung customer.source.updated, wenn das Bankkonto ordnungsgemäß verifiziert wurde. Der status des Bankkontos wird auf verified gesetzt.
• Wenn das Bankkonto nicht verifiziert wird, weil eine der beiden Mikroeinzahlungen nicht ausgeführt werden konnte, erhalten Sie die Benachrichtigung customer.source.updated. Der status des Bankkontos wird auf verification_failed gesetzt.

Connect-Unterstützung

Mit Connect kann Ihre Plattform Geld verdienen, während Zahlungen abgewickelt werden. Sie haben folgende Möglichkeiten:

• Erstellen Sie den Kunden/die Kundin für das verbundene Konto und erstellen Sie anschließend eine Direct Charge.
• Erstellen Sie den/die Kund/in für das Plattformkonto und erstellen Sie anschließend eine Destination Charge unter Verwendung des Parameters transfer_data (wie im folgenden Code).

curl https://api.stripe.com/v1/charges \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1500 \
  -d currency=usd \
  -d customer=cus_AFGbOSiITuJVDs \
  -d "transfer_data[amount]"=850 \
  -d "transfer_data[destination]"={{CONNECTED_STRIPE_ACCOUNT_ID}}

Rahmenvertrag

Die Nutzung der Live-Modus-API unterliegt dem Rahmenvertrag von Stripe. Wenn Sie Fragen zu diesem Vertrag haben, kontaktieren Sie uns bitte.